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I was introduced to Microsoft Windows CE right before it was released in the fall of 
1996. A Windows programmer for many years, I was intrigued by an operating sys- 
tem that applied the well-known Windows API to a smaller, more power-conserving 
operating system. The distillation of the API for smaller machines enables tens of 
thousands of Windows programmers to write applications for an entirely new class 
of systems. The subtle differences, however, make writing Windows CE code some- 
what different from writing for Windows 98 or Windows NT. It’s those differences 
that P’ll address in this book. 


JUST WHAT IS WINDOWS CE? 


Windows CE is the newest, smallest, and arguably the most interesting of the Micro- 
soft Windows operating systems. Windows CE was designed from the ground up to 
be a small, ROM-based operating system with a Win32 subset API. Windows CE ex- 
tends the Windows API into the markets and machines that can’t support the larger 
footprints of Windows 98 and Windows NT. 

Windows 98 is a great operating system for users who need backward compati- 
bility with DOS and Windows 2.x and 3.x programs. While it has shortcomings, Win- 
dows 98 succeeds amazingly well at this difficult task. Windows NT, on the other hand, 
is written for the enterprise. It sacrifices compatibility and size to achieve its high level 
of reliability and robustness. 

Windows CE isn’t backward compatible with MS-DOS or Windows. Nor is it 
an all-powerful operating system designed for enterprise computing. Instead, Win- 
dows CE is a lightweight, multithreaded operating system with an optional graphi- 
cal user interface. Its strength lies in its small size, its Win32 subset API, and its 
multiplatform support. 


PRODUCTS BASED ON WINDOWS CE 


The first products designed for Windows CE were handheld “organizer” type devices 
with 480-by-240 or 640-by-240 screens and chiclets keyboards. These devices, dubbed 
Handheld PCs, were first introduced at Fall Comdex 96. Fall Comdex 97 saw the re- 
lease of a dramatically upgraded version of the operating system, Windows CE 2.0, 
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with newer hardware in a familiar form—this time the box came with a 640-by-240 
landscape screen and a somewhat larger keyboard. 

In January 1998 at the Consumer Electronics Show, Microsoft announced two 
new platforms, the Palm-size PC and the Auto PC: The Palm-size PC was aimed di- 
rectly at the pen-based organizer market currently dominated by the Palm Pilot. The 
Palm-size PC sports a portrait mode, 240-by-320 screen and uses stylus-based input. 
A number of Palm-size PCs are on the market today. 

Figure I-1 shows both a Palm-size PC, in this case a Casio E-10, and a Handheld 
PC, in this case a Casio A-20. 


Figure I-1. 7he Casio E-10 Palm-size PC and the Casio A-20 Handheld PC. 


Just as this book is being released, Microsoft has introduced the Handheld PC 
Professional, which is a greatly enhanced H/PC with new applications and which uses 
the latest version of the operating system, Windows CE 2.11.’ This device brings the 
compact nature of Windows CE to devices of laptop size. The advantages of apply- 
ing Windows CE to a laptop device are many. First, the battery life of a Handheld PC 
Pro is at least 10 hours, far better than the 2-to 3-hour average of a PC-compatible 
laptop. Second, the size and weight of the Windows CE devices are far more user 
friendly, with systems as thin as 1 inch weighing less than 3 pounds. Even with the 
diminutive size, a Handheld PC Pro still sports a large VGA screen and a keyboard 
that a normal human can use. The Vadem Clio Handheld PC Pro, shown in Figure I-2, 
is an example of how Windows CE is being used in newer platforms. The system 


1. Windows CE 2.11 is Windows CE 2.10 with a few minor changes. 
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can be used as a standard laptop or “flipped” into a tablet-mode device. This de- 
vice is just one example of how Windows CE is expanding into new system types. 


Figure I-2. The Vadem Clio Handheld PC Pro. 


I refer to the Handheld PC Pro throughout this book under its operating system 
version, Windows CE 2.1, because the platform name, Handheld PC Pro, was deter- 
mined very late in the process. I knew of, and in fact, had a hand in the development 
of a Handheld PC Pro under its code name Jupiter. However, you can’t use code names 
in a book, so its operating system version had to suffice. 

Other platforms—Auto PC, Web TV set-top boxes, and embedded platforms 
designed for specific tasks—are also appearing or will appear in the coming months. 
What's amazing about Windows CE is that the flexibility of the operating system al- 
lows it to be used in all these diverse designs while all the time retaining the same 
basic, well-known Win32 API. 


WHY YOU SHOULD READ THIS BOOK 


Programming Microsoft Windows CE is written for anyone who will be writing appli- 
cations for Windows CE. Both the embedded systems programmer using Windows CE 
for a specific application and the Windows programmer interested in porting an ex- 
isting Windows application or writing an entirely new one can use the information 
in this book to make their tasks easier. 

The embedded systems programmer, who might not be as familiar with the 
Win32 API as the Windows programmer, can read the first section of the book to 
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become familiar with Windows programming. While this section isn’t the compre- 
hensive tutorial that can be found in books such as Programming Windows by Charles 
Petzold, it does provide a base that will carry the reader through the other chapters 
in the book. It also can help the embedded systems programmer develop fairly com- 
plex and quite useful Windows CE programs. 

The experienced Windows programmer can use the book to learn about the 
differences among the Win32 APIs used by Windows CE, Windows NT, and Windows 
98. Programmers who are familiar with Win32 programming recognize subtle differ- 
ences between the Windows 98 and Windows NT APIs. The differences between 
Windows CE and its two cousins are even greater. The small footprint of Windows CE 
means that many of the overlapping APIs in the Win32 model aren’t supported. Some 
sections of the Win32 API aren’t supported at all. On the other hand, because of its 
unique setting, Windows CE extends the Win32 API in a number of areas that are 
covered in this text. | 

The method used by Programming Windows CE is to teach by example. I wrote 
numerous Windows CE example programs specifically for this book. The source for 
each of these examples is printed in the text. Both the source and the final compiled 
programs for a number of the processors supported by Windows CE are also pro- 
vided on the accompanying CD. 

_ The examples in this book are all written directly to the API, the so-called 
“Petzold” method of programming. Since the goal of this book is to teach you how to 
write programs for Windows CE, the examples avoid using a class library such as MFC, 
which obfuscates the unique nature of writing applications for Windows CE. Some 
people would say that the availability of MFC on Windows CE eliminates the need for 
direct knowledge of the Windows CE API. I believe the opposite is true. Knowledge 
of the Windows CE API enables more efficient use of MFC. I also believe that truly know- 
ing the operating system also dramatically simplifies the debugging of applications. 


WHAT ABOUT MFC? 


The simple fact is that Windows CE systems aren’t the best platform for a general- 
purpose class library like MFC. The slower processors and the significantly lower 
memory capacity of Windows CE devices make using MFC problematic. Most Win- 
dows CE systems don’t include the MFC library in their ROM. This means that the 
MFC and OLE32 DLLs required by MFC applications must be downloaded into the 
systems. The first versions of the Palm-size PCs don’t even support MFC. 

That said, there’s a place for MFC on Windows CE devices. One such place might 
be if you’re designing a custom application for a system you know will have the MFC 
and OLE32 DLLs in ROM. For those specific applications, you might want to use MFC, 
but only if you know the target environment and have configured the system with 
the proper amount of RAM to do the job. 
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WINDOWS CE DEVELOPMENT TOOLS 


This book is written with the assumption that the reader knows C and is at least fa- 
miliar with Microsoft Windows. All code development was done with Microsoft Vi- 
sual C++ 5.0 and Windows CE Visual C++ for Windows CE under Windows NT 4.0. 

To compile the example programs in this book, you need Microsoft Visual C++ 5.0, 
which is part of the integrated development environment (DE), DevStudio, run- 
ning on a standard IBM-compatible PC. You also need Microsoft Visual C++ for 
Windows CE, which isn’t a stand-alone product. It’s an add-in to Visual C++ 5.0 that 
incorporates components to the compiler that produce code for the different CPUs 
supported by Windows CE. Visual C++ for Windows CE isn’t currently available through 
standard retail channels, but information on ordering it directly from Microsoft can 
be found on the Microsoft Web site. Finally, you need one of the platform SDKs for 
Windows CE. These SDKs provide the custom include files for each of the Windows 
CE platforms. These platform SDKs are available for free on the Microsoft Web site. 
As a convenience, I’ve also included the platform SDKs available at the time of the 
writing of this book on the accompanying CD. 

While not absolutely required for developing applications for Windows CE, 
Windows NT 4.0 is strongly recommended for the development environment. It’s 
possible to compile and download Windows CE programs under Windows 98, but 
many of the features of the integrated development environment (IDE), such as Win- 
dows CE emulation and remote debugging, aren’t supported. 

Visual C++ for Windows CE won’t change the outward appearance of Visual C++, 
with the exception of a few new tools listed under the tools menu. Nor will the in- 
stallation of Visual C++ for Windows CE prevent you from developing applications 
for other Windows operating systems. The installation of Visual C++ for Windows CE 
will result in new Windows CE targets such as WCE MIPS and WCE SH and WCE x86Em 
being added to the platforms listing when you're creating a new Win32 application. 
Also, a Windows CE MFC AppWizard will be added to the new projects listing to assist 
in creating MFC programs for Windows CE. 


TARGET SYSTEMS 


You don’t need to have a Windows CE target device to experience the sample pro- 
grams provided by this book. The various platform SDKs come with a Windows CE 
emulator that lets you perform basic testing of a Windows CE program under Win- 
dows NT. This emulator comes in handy when you want to perform initial debugging 
to ensure that the program starts, creates the proper windows, reacts to menu selec- 
tions, and so on. However, the emulator has some limitations and there simply is no 
replacement for having a target Windows CE system to perform final debugging and 
testing for applications. 
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You should consider a number of factors when deciding what Windows CE 
hardware to use for testing. First, if the application is to be a commercial product, 
you should buy at least one system for each type of target CPU. You need to test against 
all of the target CPUs because, while the source code will probably be identical, the 
resulting executable will be different in size and so will the memory allocation foot- 
print for each target CPU. 

Most applications will also be written specifically for the Handheld PC or Palm- 
size PC, not both. Although the base operating system for both the Handheld PC and 
Palm-size PC is Windows CE, the hardware underneath is vastly different. The strict 
memory constraints of the Palm-size PC, as well as its much smaller screen, its differ- 
ent orientation, and its lack of a keyboard, force compromises that aren’t acceptable 
on a Handheld PC or its larger relative, the Handheld PC Pro. Other constraints on 
Palm-size PC systems, such as the lack of printing and TrueType support, differenti- 
ate its environment from the Handheld PC’s. 

In this book, I demonstrate programs that can run on the Handheld PC, 
Handheld PC Pro, or Palm-size PC. The goal is to allow the lessons to be applied to 
all platforms. For some examples, however, the different screen dimensions mean 
that the example will run better on one particular system. I point out the differences 
and the reasons they exist. For example, some controls might exist on only one plat- 
form or the other. The shells for the two platforms—Handheld or Palm-size—are also 
different and need separate coverage. Finally, a small set of features in Windows CE 
are simply not supported on the smaller Palm-size PC platform. 


WHAT’S ON THE CD 


The accompanying CD contains the source code for all the examples in the book. 
I’ve also provided project files for Microsoft DevStudio so that you can open 
preconfigured projects. Unless otherwise noted, the examples are Windows CE 2.0 
compatible so that they can run on most Windows CE systems available today. Chap- 
ter 13, “Shell Programming—Part 2” contains examples that are compiled for 
Windows CE 2.01, so they won’t run on current Handheld PCs. There are some ex- 
amples, such as the console applications in Chapter 12, that are specific to the 
Handheld PC Pro and other devices running Windows CE 2.10. 

When you build for a specific platform, remember that it might not be back- 
ward compatible with earlier versions of Windows CE. For example, Microsoft moved 
some of the C library support from statically linked libraries in Windows CE 2.0 into 
the operating system for Windows CE 2.01, the Palm-size PC release. This reduces 
the size of an executable, but prevents code built for the Palm-size PC from running 
on a Handheld PC running Windows CE 2.0. You can, however, compile code for a 
Handheld PC running Windows CE 2.0 and have it run on a Palm-size PC. 
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In addition to the examples, the CD contains a number of folders of interest to 
the Windows CE programmer. I’ve included the platform SDKs for the Handheld PC 
as well as for the Palm-size PC. Unfortunately, the Handheld PC Pro SDK wasn’t avail- 
able in time for this release. Like the other platform SDKs, that one is available for 
free on the Microsoft Web site. Check out the readme file on the CD for late-breaking 
information about what else is included on the CD. 


OTHER SOURCES 


While I have attempted to make Programming Microsoft Windows CE a one-stop shop 
for Windows CE programming, no one book can cover everything. A nice comple- 
ment to this book is Inside Windows CE by John Murray. It documents the “oral his- 
tory” of Windows CE. Knowing this kind of information is crucial to understanding 
just why Windows CE is designed the way it is. Once you know the why, it’s easy to 
extrapolate the what, when trying to solve problems. Murray’s book is great, not just 
because of the information you’ll learn about Windows CE but also because it’s an 
entertaining read. 

For learning more about Windows programming in general, I suggest the clas- 
sic text Programming Windows by Charles Petzold. This is, by far, the best book for 
learning Windows programming. Charles presents examples that show how to tackle 
difficult but common Windows problems. For learning more about the Win32 kernel 
API, I suggest Jeff Richter’s Advanced Windows. Jeff covers the techniques of pro- 
cess, thread, and memory management down to the most minute detail. For learning 
more about MFC programming, there’s no better text than Jeff Prosise’s Programming 
Windows 95 with MFC. This book is the “Petzold” of MFC programming and simply 
a required read for MFC programmers. 


FEEDBACK 


While I have striven to make the information in this book as accurate as possible, 
you'll undoubtedly find errors. If you find a problem with the text or just have ideas 
about how to make the next version of the book better, please drop me a note at 
CEBook@DelValle.com. J can’t promise you that Pll answer all your notes, but I will 
read every one. 


Doug Boling 
Tahoe City, California 
August 1998 
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Chapter 1 


Hello Windows CE 


From Kernighan and Ritchie to Petzold and on to Prosise, programming books tradition- 
ally start with a “hello, world” program. It’s a logical place to begin. Every program has 
a basic underlying structure that, when not obscured by some complex task it was de- 
signed to perform, can be analyzed to reveal the foundation shared by all programs 
running on its operating system. 

In this programming book, the “hello, world” chapter covers the details of set- 
ting up and using the programming environment. The environment for developing 
Microsoft Windows CE applications is somewhat different from that for developing 
standard Microsoft Windows applications because Windows CE programs are writ- 
ten on PCs running Microsoft Windows NT and debugged mainly on separate, Win- 
dows CE-based target devices. 

While experienced Windows programmers might be tempted to skip this chap- 
ter and move on to meatier subjects, I suggest that they—you—at least skim the chapter 
to note the differences between a standard Windows program and a Windows CE 
program. A number of subtle and significant differences in both the development 
process and the basic program skeleton for Windows CE applications are covered in 
this first chapter. 


WHAT IS DIFFERENT ABOUT WINDOWS CE? 


Windows CE has a number of unique characteristics that make it different from other 
Windows platforms. First of all, the systems running Windows CE are most likely not 
using an Intel x86 compatible microprocessor. Instead, a short list of supported CPUs 
run Windows CE. Fortunately, the development environment isolates the program- 
mer from almost all of the differences among the various CPUs. 
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Nor can a Windows CE program be assured of a screen or a keyboard. Some Win- 
dows CE devices have a 240-by-320-pixel portrait-style screen while others might have 
screens with more traditional landscape orientations in 480-by-240, 640-by-240, or 640- 
by-480-pixel resolution. An embedded device might not have a display at all. The tar- 
get devices might not support color. And, instead of a mouse, most Windows CE 
devices have a touch screen. On a touch-screen device, left mouse button clicks are 
achieved by means of a tap on the screen, but no obvious method exists for delivering 
right mouse button clicks. To give you some method of delivering a right click, the 
Windows CE convention is to hold down the Alt key while tapping. It’s up to the Win- 
dows CE application to interpret this sequence as a right mouse click. 


Fewer Resources in Windows CE Devices 


The resources of the target devices vary radically across systems that run Windows CE. 
When writing a standard Windows program, the programmer can make a number of 
assumptions about the target device, almost always an IBM-compatible PC. The tar- 
get device will have a hard disk for mass storage and a virtual memory system that 
uses the hard disk as a swap device to emulate an almost unlimited amount of Cvir- 
tual) RAM. The programmer knows that the user has a keyboard, a two-button mouse, 
and a monitor that these days almost assuredly supports 256 colors and a screen reso- 
lution of at least 640 by 480 pixels. 

Windows CE programs run on devices that almost never have hard disks for 
mass storage. The absence of a hard disk means more than just not having a place to 
store large files. Without a hard disk, virtual RAM can’t be created by swapping data 
to the disk. So Windows CE programs are almost always run in a low-memory envi- 
ronment. Memory allocations can, and often do, fail because of the lack of resources. 
Windows CE might terminate a program automatically when free memory reaches a 
critically low level. This RAM limitation has a surprisingly large impact on Windows CE 
programs and is one of the main difficulties involved in porting existing Windows 
applications to Windows CE. 


Unicode 


One characteristic that a programmer can count on when writing Windows CE applica- 
tions is Unicode. Unicode is a standard for representing a character as a 16-bit value as 
opposed to the ASCII standard of encoding a character into a single 8-bit value. Unicode 
allows for fairly simple porting of programs to different international markets because 
all the world’s known characters can be represented in one of the 65,536 available 
Unicode values. Dealing with Unicode is relatively painless as long as you avoid the 
dual assumptions made by most programmers that strings are represented in ASCII 
and that characters are stored in single bytes. 
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A consequence of a program using Unicode is that with each character taking up 
two bytes instead of one, strings are now twice as long. A programmer must be careful 
making assumptions about buffer length and string length. No longer should you as- 
sume that a 260-byte buffer can hold 259 characters and a terminating zero. Instead of 
the standard char data type, you should use the TCHAR data type. TCHAR is defined to 
be char for Microsoft Windows 95 and Microsoft Windows 98 development and unsigned 
short for Unicode-enabled applications for Microsoft Windows NT and Windows CE 
development. These types of definitions allow source-level compatibility across ASCII- 
and Unicode-based operating systems. 


New Controls 


Windows CE includes a number of new Windows controls designed for specific envi- 
ronments. New controls include the command bar that provides menu- and toolbar- 
like functions all on one space-saving line, critical on the smaller screens of Windows CE 
devices. The date and time picker control and calendar control assist calendar and or- 
ganizer applications suitable for handheld devices, such as the Handheld PC (H/PC) 
and the Palm-size PC. Other standard Windows controls have reduced function, 
reflecting the compact nature of Windows CE hardware-specific OS configurations. 

Another aspect of Windows CE programming to be aware of is that Windows CE 
can be broken up and reconfigured by Microsoft or by OEMs so that it can be better 
adapted to a target market or device. Windows programmers usually just check the 
version of Windows to see whether it is from the Microsoft Windows 3.1, 95, or 98 
line or Windows NT line; by knowing the version they can determine what API func- 
tions are available to them. Windows CE, however, has had four variations already in 
its first two years of existence: the Handheld PC, the Palm-size PC, the Handheld PC 
Pro, and the Auto PC. A number of new platforms are on their way, with much in 
common but also with many differences among them. Programmers need to under- 
stand the target platform and to have their programs check what functions are avail- 
able on that particular platform before trying to use a set of functions that might not 
be supported on that device. 

Finally, because Windows CE is so much smaller than Windows 98 or Win- 
dows NT, it simply can’t support all the function calls that its larger cousins do. While 
you'd expect an operating system that didn’t support printing, such as Windows CE on 
the original Palm-size PC, not to have any calls to printing functions, Windows CE also 
removes some redundant functions supported by its larger cousins. If Windows CE 
doesn’t support your favorite function, a different function or set of functions will 
probably work just as well. Sometimes Windows CE programming seems to consist 
mainly of figuring out ways to implement a feature using the sparse API of Windows CE. 
If 2000 functions can be called sparse. 
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IT’S STILL WINDOWS PROGRAMMING 


While differences between Windows CE and the other versions of Windows do exist, 
they shouldn’t be overstated. Programming a Windows CE application is program- 
ming a Windows application. It has the same message loop, the same windows, and 
for the most part, the same resources and the same controls. The differences don’t 
hide the similarities. For those who aren’t familiar with Windows programming, here’s 
a short introduction. 

Windows programming is far different from MS-DOS-—based or Unix-based pro- 
gramming. An MS-DOS or Unix program uses geftc- and putc-style functions to read 
characters from the keyboard and write them to the screen whenever the program 
needs to do so. This is the classic “pull” style used by MS-DOS and Unix programs, 
which are procedural. A Windows program, on the other hand, uses a “push” model, 
in which the program must be written to react to notifications from the operating system 
that a key has been pressed or a command has been received to repaint the screen. 

Windows applications don’t ask for input from the operating system; the oper- 
ating system notifies the application that input has occurred. The operating system 
achieves these notifications by sending messages to an application window. All win- 
dows are specific instances of a window class. Before we go any further, let’s be sure 
we understand these terms. 


The Window Class 


A window is a region on the screen, rectangular in all but the most contrived of cases, 
that has a few basic parameters, such as position—x, y, and z (a window is over or 
under other windows on the screen)—visibility, and hierarchy—the window fits into 
a parent/child window relationship on the system desktop, which also happens to be 
a window. 

Every window created is a specific instance of a window class. A window class 
is a template that defines a number of attributes common to all the windows of that 
class. In other words, windows of the same class have the same attributes. The most 
important of the shared attributes is the window procedure. 


The window procedure 
The behavior of all windows belonging to a class is defined by the code in its win- 
dow procedure for that class. The window procedure handles all notifications and 
requests sent to the window. These notifications are sent either by the operating sys- 
tem, indicating that an event has occurred to which the window must respond, or by 
other windows querying the window for information. 

These notifications are sent in the form of messages. A message is nothing more 
than a call being made to a window procedure, with a parameter indicating the nature 
of the notification or request. Messages are sent for events such as a window being moved 
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or resized or to indicate a key press. The values used to indicate messages are defined 
by Windows. Applications use predefined constants, such as WM_CREATE or WM_MOVE, 
when referring to messages. Since hundreds of messages can be sent, Windows conve- 
niently provides a default processing function to which a message can be passed when 
no special processing is necessary by the window class for that message. 


The life of a message 
Stepping back for a moment, let’s look at how Windows coordinates all of the mes- 
sages going to all of the windows in a system. Windows monitors all the sources of 
input to the system, such as the keyboard, mouse, touch screen, and any other hard- 
ware that could produce an event that might interest a window. As an event occurs, 
a message is composed and directed to a specific window. Instead of Windows di- 
rectly calling the window procedure, the system imposes an intermediate step. The 
message is placed in a message queue for the application that owns the window. When 
the application is prepared to receive the message, it pulls it out of the queue and 
tells Windows to dispatch that message to the proper window in the application. 

If it seems to you that a number of indirections are involved in that process, 
you're right. Let’s break it down. 


1. An event occurs, so a message is composed by Windows and placed in a 
message queue for the application that owns the destination window. In 
Windows CE, as in Windows 95 and Windows NT, each application has 
its own unique message queue’. (This is a break from Windows 3.1 and 
earlier versions of Windows, where there was only one, systemwide mes- 
sage queue.) Events can occur, and therefore messages can be composed, 
faster than an application can process them. The queue allows an appli- 
cation to process messages at its own rate, although the application had 
better be responsive or the user will see a jerkiness in the application. The 
message queue also allows Windows to set a notification in motion and 
continue with other tasks without having to be limited by the responsive- 
ness of the application to which the message is being sent. 


2. The application removes the message from its message queue and calls 
Windows back to dispatch the message. While it may seem strange that 
the application gets a message from the queue and then simply calls Win- 
dows back to process the message, there’s a method to this madness. 
Having the application pull the message from the queue allows it to pre- 
process the message before it asks Windows to dispatch the message to 


1. Technically, each thread in a Windows CE application can have a message queue. I'll talk about 
threads later in the book. 
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the appropriate window. In a number of cases, the application might call 
different functions in Windows to process specific kinds of messages. 


3. Windows dispatches the message; that is, it calls the appropriate window 
procedure. Instead of having the application directly call the window pro- 
cedure, another level of indirection occurs, allowing Windows to coordi- 
nate the call to the window procedure with other events in the system. 
The message doesn’t stand in another queue at this point, but Windows 
might need to make some preparations before calling the window proce- 
dure. In any case, the scheme relieves the application of the obligation to 
determine the proper destination window—Windows does this instead. 


4. The window procedure processes the message. All window procedures 
have the same calling parameters: the handle of the specific window in- 
stance being called, the message, and two generic parameters that con- 
tain data specific to each message type. The window handle differentiates 
each instance of a window for the window procedure. The message pa- 
rameter, of course, indicates the event that the window must react to. The 
two generic parameters contain data specific to the message being sent. 
For example, ina WM_MOVE message indicating that the window is about 
to be moved, one of the generic parameters points to a structure contain- 
ing the new coordinates of the window. 


Your First Program 


Enough small talk. It’s time to jump into the first example, Hello Windows CE. While 
the entire program files for this and all examples in the book are available on the 
companion CD-ROM, I suggest that, at least in this one case, you avoid simply load- 
ing the project file from the CD and instead type in the entire example by hand. By 
performing this somewhat tedious task, you'll see the differences in the development 
process as well as the subtle program differences between standard Win32 programs 
and Windows CE programs. Figure 1-1 contains the complete source for HelloCE, my 
version of a hello, world program. 


Figure 1-1. 7he HelloCE program. 


Chapter 1 Hello Windows CE 


(continued) 


ever ert 


continued 


-1 


igure 1 


F 


10 


Chapter 1 Hello Windows CE 


(continued) 


11 


Figure 1-1. continued 


SS 


12 


See 


14 


If you look over the source code for HelloCE, you'll see the standard boilerplate 
for all programs in this book. I’ll talk at greater length about a few of the characteris- 
tics, such as Hungarian notation and the somewhat different method I use to con- 
struct my window procedures later, in their own sections, but at this point Pll make 
just a few observations about them. 

Just after the comments, you see the include of windows.h. You can find this 
file in all Windows programs; it lists the definitions for the special variable types and 
function defines needed for a typical program. Windows.h and the include files it 
contains make an interesting read because the basics for all windows programs come 
from the functions, typedefs, and structures defined there. The include of commctrl.h 
provides, among other things, the definitions for the command bar functions that are 
part of almost all Windows CE programs. Finally, the include of HelloCE.h gives you 
the boilerplate definitions and function prototypes for this specific program. 

A few variables defined globally follow the defines and includes. I know plenty 
of good arguments why no global variables should appear in a program, but I use 
them as a convenience that shortens and clarifies the example programs in the book. 
Each program defines an szAppName Unicode string to be used in various places in 
that program. I also use the binst variable a number of places and I'll mention it when 
I cover the InitApp procedure. The final global structure is a list of messages along 
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with associated procedures to process the messages. This structure is used by the win- 
dow procedure to associate messages with the procedure that handles them. Now, 
on to a few other characteristics common to all the programs in this book. 


Hungarian Notation 


A tradition, and a good one, of almost all Windows programs since Charles Petzold wrote 
Programming Windows is Hungarian notation. This programming style, developed years 
ago by Charles Simonyi at Microsoft, prefixes all variables in the program usually with 
one or two letters indicating the variable type. For example, a string array called Name 
would instead be called szName, with the sz prefix indicating that the variable type 
is a zero-terminated string. The value of Hungarian notation is the dramatic improvement 
in readability of the source code. Another programmer, or you after not looking at a 
piece of code for a while, won’t have to look repeatedly at a variable’s declaration to 
determine its type. The following are typical Hungarian prefixes for variables: 


Variable Type . Hungarian Prefix 
Integer torn 
Word (16-bit) Ww or S$ 
Double word (32-bit unsigned) dw 
Long (32-bit signed) i 
Char Cc 
String SZ 
Pointer D 
Long pointer lp 
Handle h 
Window handle hwnd 
Struct size cb 


You can see a few vestiges of the early days of Windows. The /p, or long pointer, 
designation refers to the days when, in the Intel 16-bit programming model, pointers 
were either short (a 16-bit offset) or long (a segment plus an offset). Other prefixes 
are formed from the abbreviation of the type. For example, a handle to a brush is 
typically specified as hbr. Prefixes can be combined, as in /psz, which designates a 
long pointer to a zero-terminated string. Most of the structures defined in the Windows 
API use Hungarian notation in their field names. I use this notation as well throughout 
the book, and I encourage you to use this notation in your programs. 
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My Programming Style 


One criticism of the typical SDK style of Windows programming has always been the 
huge switch statement in the window procedure. The switch statement parses the 
message to the window procedure so that each message can be handled indepen- 
dently. This standard structure has the one great advantage of enforcing a similar struc- 
ture across almost all Windows applications, making it much easier for one programmer 
to understand the workings of another programmer’s code. The disadvantage is that 
all the variables for the entire window procedure typically appear jumbled at the top 
of the procedure. 

Over the years, I’ve developed a different style for my Windows programs. The 
idea is to break up the WinMain and WinProc procedures into manageable units that 
can be easily understood and easily transferred to other Windows programs. WinMain 
is broken up into procedures that perform application initialization, instance initial- 
ization, and instance termination. Also in WinMain is the ubiquitous message loop 
that’s the core of all Windows programs. 

I break the window procedure into individual procedures, with each handling 
a specific message. What remains of the window procedure itself is a fragment of 
code that simply looks up the message that’s being passed to see whether a proce- 
dure has been written to handle that message. If so, that procedure is called. If not, 
the message is passed to the default window procedure. 

This structure divides the handling of messages into individual blocks that can 
be more easily understood. Also, with greater isolation of one message-handling code 
fragment from another, you can more easily transfer the code that handles a specific 
message from one program to the next. I first saw this structure described a number 
of years ago by Ray Duncan in one of his old “Power Programming” columns in PC 
Magazine. Ray is one of the legends in the field of MS-DOS and OS/2 programming. 
I’ve since modified the design a bit to fit my needs, but Ray should get the credit for 
this program structure. 


Building HelloCE 
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To create HelloCE from scratch on your system, start Microsoft Visual C++ and create a 
new Win32 application. The first change from standard Win32 programming becomes 
evident when you create the new project. You'll have the opportunity to select a new 
platform specific to Windows CE, as shown in Figure 1-2. These platforms have a WCE 
prefix followed by the target CPU. For example, selecting Win32 (WCE MIPS) enables 
compiling to a Windows CE platform with a MIPS CPU. No matter what target device 
you have, be sure to check the WCE x86em target. This allows you to run the sample 
program in the emulator under Windows NT. 
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Figure 1-2. 7he Platforms list box allows Visual C++ 5.0 to target Windows CE 
platforms. 


After you have created the proper source files for HelloCE or copied them from 
the CD, select the target Win32 (WCE x86em) Debug and then build the program. 
This step compiles the source and, assuming you have no compile errors, automati- 
cally launches the emulator and inserts the EXE into the emulator file system; you 
can then launch HelloCE. If you’re running Windows 95 or Windows 98, the system 
displays an error message because the emulator runs only under Windows NT. 

If you have a Windows CE system available, such as an H/PC, attach the H/PC 
to the PC the same way you would to sync the contents of the H/PC with the PC. 
Open the Mobile Devices folder and establish a connection between the H/PC and 
the PC. While it’s not strictly necessary to have the Mobile Devices connection to your 
Windows CE device running because the SDK tools inside Visual C++ are supposed 
to make this connection automatically, I’ve found that having it running makes for 
a more stable connection between the development environment and the 
Windows CE-system. 

Once the link between the PC and the Windows CE device is up and running, 
switch back to Visual C++, select the compile target appropriate for the target device 
(for example, Win32 [WCE SH] Debug for an HP 360 HPC), and rebuild. As in the 
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case of building for the emulator, if there are no errors Visual C++ automatically down- 
loads the compiled program to the remote device. The program is placed in the root 
directory of the object store. 


Running the program 

To run HelloCE on an H/PC, simply click on the My Handheld PC icon to bring up the 
files in the root directory. At that point, a double-tap on the application’s icon launches 
the program. 

Running the program on a Palm-size PC is somewhat more complex. Because 
the Palm-size PC doesn’t come with an Explorer program that allows users to browse 
through the files on the system, you can’t launch HelloCE without a bit of prepara- 
tory work. You can launch the program from Visual C++ by selecting Execute from 
the Build menu. Or you can have Visual C++ automatically copy the executable file 
into the \windows\start menu\programs directory of the Palm-size PC. This auto- 
matically places the program in the Programs submenu under the Start menu. You 
can tell Visual C++ to automatically copy the file by setting the remote target path in 
the Debug tab of the Project Settings dialog box. Figure 1-3 shows this dialog box. When 
you've set this path, you can easily start the program by selecting it in the Start menu. 
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Figure 1-3. The Project Settings dialog box in Visual C++ with the Debug tab selected. 


One “gotcha” to look out for here. If you're debugging and recompiling the 
program, it can’t be downloaded again if an earlier version of the program is still 
running on the target system. That is, make sure HelloCE isn’t running on the re- 
mote system when you start a new build in Visual C++ or the auto download part 
of the compile process will fail. If this happens, close the application and choose 
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the Update Remote File menu command in Visual C++ to download the newly com- 
piled file. 

Palm-size PC users will notice that unlike almost all Palm-size PC programs, HelloCE 
has a Close button in the upper right corner of the window. By convention, the user 
doesn’t close Palm-size PC applications; they’re closed only when the system needs 
more memory space. The lack of a Close button in Palm-size PC applications is only 
a user interface guideline, not a lack of function of the version of Windows CE in the 
Palm-size PC. For development, you might want to keep a Close button in your appli- 
cation because you'll need to close the program to download a new version. You can 
then remove the Close button before you ship your application. 

If you don’t have access to an H/PC or if you want to check out Windows CE 
programming without the hassle of connecting to a remote device, the emulation 
environment is a great place to start. It’s the perfect place for stepping though the 
code just as you would were you debugging a standard PC-based Windows program. 
You can set breakpoints and step though code running on a remote system, but the 
slow nature of the serial link as well as the difficulty in single-stepping a program on 
the remote system make debugging on the emulator much less painful. On the other 
hand, debugging on the remote system is the only way to truly test your program. While 
the emulator is a good first step in the debug process, nothing replaces testing on the 
target system. 


The code 

Now that you have the program up and running either in the emulator or on a Win- 
dows CE device, it’s time to look at the code itself. The program entry point, WinMain, 
is the same place any Windows program begins. Under Windows CE, however, some 
of the parameters for WinMain have limits to the allowable values. WinMain is de- 
fined as the following: 


int WINAPI WinMain (CHINSTANCE hInstance, HINSTANCE hPrevInstance, 
LPWSTR IpCmdLine, int nCmdShow) ; 


The first of the four parameters passed, binstance, identifies the specific instance 
of the program to other applications and to Windows API functions that need to identify 
the EXE. The hPrevinstance parameter is left over from the old Win16 API (Win- 
dows 3.1 and earlier). In those versions of Windows, the bPrevinstance parameter 
was nonzero if there were any other instances of the program currently running. In 
all Win32 operating systems, including Windows CE, the Previnstance is always 0 
and can be ignored. 

The /CmdLine parameter points to a Unicode string that contains the text of 
the command line. Applications launched from Microsoft Windows Explorer usu- 
ally have no command line parameters. But in some instances, such as when the 
system automatically launches a program, the system includes a command line 
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parameter to indicate why the program was started. The /CmdLine parameter provides 
us with one of the first instances in which Windows CE differs from Windows NT or 
Windows 98. Under Windows CE, the command line string is a Unicode string. In Win- 
dows NT and Windows 98, the string is always ASCII. 

The final parameter, 7SbowCmd, specifies the initial state of the program’s main 
window. In a standard Win32 program, this parameter might specify that the window 
be initially displayed as an icon (SW_SHOWMINIMIZE), maximized (SW_SHOW- 
MAXIMIZED) to cover the entire desktop, or normal (SW_RESTORE), indicating that 
the window is placed on the screen in the standard resizable state. Other values 
specify that the initial state of the window should be invisible to the user or that the 
window be visible but incapable of becoming the active window. Under Windows 
CE, the values for this parameter are limited to only three allowable states: normal 
(SW_SHOW), hidden (SW_HIDE), or show without activate (SW_SHOWNO- 
ACTIVATE). Unless an application needs to force its window to a predefined state, this 
parameter is simply passed without modification to the ShowWindow function after the 
program’s main window has been created. 

On entry into WinMain, a call is made to InitApp, where the window class for the 
main window is registered. After that, a call to InitInstance is made; the main window 
is created in this function. I'll talk about how these two routines operate shortly, but for 
now Ill continue with WinMain, proceeding on the assumption that at the return from 
InitInstance the program’s main window has been created. 


The message loop 
After the main window has been created, WinMain enters the message loop, which 
is the heart of every Windows application. HelloCE’s message loop is shown here: 


while (GetMessage (&msg, NULL, 0, @)) { 
TranslateMessage (&msg); 
DispatchMessage (&msg); 


The loop is simple: GetMessage is called to get the next message in the ap- 
plication’s message queue. If no message is available, the call waits, blocking that 
application’s thread until one is available. When a message is available, the call re- 
turns with the message data contained in a MSG structure. The MSG structure itself 
contains fields that identify the message, provide any message-specific parameters, 
and identify the last point on the screen touched by the pen before the message was 
sent. This location information is different from the standard Win32 message point 
data in that in Windows 9x or Windows NT the point returned is the current mouse 
position instead of the last point clicked (or tapped, as in Windows CE). 

The TranslateMessage function translates appropriate keyboard messages into 
a character message. Cll talk about others of these filter type messages, such as 
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IsDialogMsg, later.) The DispatchMessage function then tells Windows to forward the 
message to the appropriate window in the application. 

This GetMessage, TranslateMessage, DispatchMessage loop continues until Get- 
Message receives a WM_QUIT message which, unlike all other messages causes 
GetMessage to return 0. As can be seen from the while clause, a return value of 0 
by GetMessage causes the loop to terminate. 

After the message loop terminates, the program can do little else but clean up 
and exit. In the case of HelloCE, the program calls TermInstance to perform any 
necessary cleanup. HelloCE is a simple program and no cleanup is required. In more 
complex programs, TermInstance would free any system resources that aren’t auto- 
matically freed when the program terminates. 

The value returned by WinMain becomes the return code of the program. Tra- 
ditionally, the return value is the value in the wParam parameter of the last message 
(WM_QUIT). The wParam value of WM_QUIT is set when that message is sent in 
response to a PostQuitMessage call made by the application. 


initApp 

The goal of InitApp is to perform global initialization for all instances of the applica- 
tion that might run. In practice, InitApp is a holdover from Win16 days when win- 
dow classes were registered on an applicationwide basis instead of for every instance, 
as is done under Win32. Still, having a place for global initialization can have its uses 
in some applications. For a program as simple as HelloCE, the entire task of InitApp 
can be reduced to registering the application’s main window class. The entire proce- 
dure is listed below: 


int InitApp (HINSTANCE hInstance) { 
WNDCLASS we; 


// Register App Main Window class. 


we.style = Q@; // Class style flags 

wc. lpfnWndProc = MainWndProc; // Callback function 
wce.cbClsExtra = Q@; // Extra class data 
wce.cbWndExtra = Q; // Extra window data 
wce.hInstance = hInstance; // Owner handle 
we.hIcon = NULL; // Application icon 
wce.hCursor = NULL; // Default cursor 
wce.hbrBackground = (HBRUSH) = GetStockObject (WHITE_BRUSH) ; 
wc.]pszMenuName = NULL; // Must be NULL 
wc.lpszClassName = szAppName; // Class name 


if (RegisterClass (&wc) == @) return 1; 


return @; 
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Registering a window class is simply a matter of filling out a rather extensive struc- 
ture describing the class and calling the RegisterClass function. The parameters assigned 
to the fields of the WNDCLASS structure define how all instances of the main window 
for HelloCE will behave. The initial field, style, sets the class style for the window. In 
Windows CE the class styles are limited to the following: 


M cCS_GLOBALCLASS indicates that the class is global. This flag is provided only 
for compatibility because all window classes in Windows CE are process 
global. 


M CS_HREDRAYW tells the system to force a repaint of the window if the win- 
dow is sized horizontally. 


M cCS_VREDRAY tells the system to force a repaint of the window if the win- 
dow is sized vertically. 


M  CS_NOCLOSE disables the Close button if one is present on the title bar. 


CS_PARENTDC causes a window to use its parent’s device context. 


M = CS_DBLCLKS enables notification of double-clicks (double-taps under Win- 
dows CE) to be passed to the parent window. 


The /pfnWndProc field should be loaded with the address of the window’s win- 
dow procedure. Because this field is typed as a pointer to a window procedure, the 
declaration to the procedure must be defined in the source code before the field is set. 
Otherwise, the compiler’s type-checker will flag this line with a warning. 

The cbClsExtra field allows the programmer to add extra space in the class struc- 
ture to store class-specific data known only to the application. The cbWndExtra field 
is much handier. This field adds space to the Windows internal structure responsible 
for maintaining the state of each instance of a window. Instead of storing large amounts 
of data in the window structure itself, an application should store a pointer to an 
application-specific structure that contains the data unique to each instance of the 
window. Under Windows CE, both the cbClsExtra and cbWndExtra fields must be 
multiples of 4 bytes. 

The hinstance field must be filled with the program’s instance handle, which 
specifies the owning process of the window. The hicon field is set to the handle of 
the window’s default icon. The bJcon field isn’t supported under Windows CE and 
should be set to NULL. Gn Windows CE, the icon for the class is set after the first 
window of this class is created. For HelloCE, however, no icon is supplied and un- 
like other versions of Windows, Windows CE doesn’t have any predefined icons that 
can be loaded.) 
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Unless the application being developed is designed for a Windows CE system 
with a mouse, the next field, bCursor, must be set to NULL. Almost all Windows CE 
systems use a touch panel instead of a mouse, so you find no cursor support in those 
systems. For those special systems that do have cursor support, the Windows CE doesn’t 
support animated cursors or colored cursors. 

The bbrBackground field specifies how Windows CE draws the background of 
the window. Windows uses the brush, a small predefined array of pixels, specified 
in this field to draw the background of the window. Windows CE provides a number 
of predefined brushes that you can load using the GetStockObject function. If the 
hbrBackground field is NULL, the window must handle the WM_ERASEBKGND 
message sent to the window telling it to redraw the background of the window. 

The IpszMenuName field must be set to NULL because Windows CE doesn’t 
support windows directly having a menu. In Windows CE, menus are provided by 
command bar or command band controls that can be created by the main window. 

Finally the /pszClassName parameter is set to a programmer-defined string that 
identifies the class name to Windows. HelloCE uses the szAppName string, which is 
defined globally. 

After the entire WNDCLASS structure has been filled out, the RegisterClass func- 
tion is called with a pointer to the WNDCLASS structure as its only parameter. If the 
function is successful, a value identifying the window class is returned. If the func- 
tion fails, the function returns 0. 


Initinstance 

The main task of InitInstance is to create the application’s main window and display 
it in the form specified in the nShowCmd parameter passed to WinMain. The code 
for InitInstance is shown below: 


HWND InitInstance (HINSTANCE hInstance, LPWSTR }pCmdLine, int nCmdShow) { 
HWND hWnd; 
HICON hIcon; 


// Save program instance handle in global variable. 
hInst = hInstance; 


// Create main window. 


hWnd = CreateWindow (szAppName, // Window class 
; TEXT("Hello”™), // Window title 
WS_VISIBLE, // Style flags 
0, Q, // xX, y position 
CW_USEDEFAULT, // Initial width 


(continued) 
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CW_USEDEFAULT, // Initial height 

NULL, // Parent 

NULL, // Menu, must be null 
hInstance, // App instance 

NULL); // Ptr to create params 


// Return fail code if window not created. 
if (!IsWindow (hWnd)) return Q@; 


// Standard show and update calls 
ShowWindow (hWnd, nCmdShow) ; 
UpdateWindow (hWnd); 


return hWnd; 


The first task performed by InitInstance is to save the program’s instance handle 
hInstance in a global variable named inst. The instance handle for a program is useful 
at a number of points in a Windows application. I save the value here because the 
instance handle is known, and this is a convenient place in the program to store it. 

All Windows programmers learn early in their Windows programming lives the 
CreateWindow function call. Although the number of parameters looks daunting, the 
parameters are fairly logical once you learn them. The first parameter is the name of 
the window class of which our window will be an instance. In the case of HelloCE, 
the class name is a string constant, szAppName, which was also used in the WNDCLASS 
structure. 

The next field is referred to as the window text. In other versions of Windows, 
this is the text that would appear on the title bar of a standard window. However, since 
Windows CE main windows rarely have title bars, this text is used only on the taskbar 
button for the window. The text is couched in a TEXT macro, which insures that the 
string will be converted to Unicode under Windows CE. 

The style flags specify the initial styles for the window. The style flags are used 
both for general styles that are relevant to all windows in the system and for class- 
specific styles, such as those that specify the style of a button or a list box. In this 
case, all we need to specify is that the window be created initially visible with the 
WS_VISIBLE flag. Experienced Win32 programmers should refer to the documenta- 
tion for CreateWindow because there are a number of window style flags that aren’t 
supported under Windows CE. 

The next four fields specify the initial position and size of the window. Since 
most applications under Windows CE are maximized (that is, they take up the entire 
screen above the taskbar), the size and position fields are set to default values, which 
are indicated by the CW_USEDEFAULT flag in each of the fields. The default value 
settings create a window that’s maximized under the current versions of Windows CE 
but also compatible with future versions of the operating system, which might not 
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maximize every window. Be careful not to assume any particular screen size for a Win- 
dows CE device because different implementations have different screen sizes. 

The next field is set to the handle of the parent window. Because this is the 
top-level window, the parent window field is set to NULL. The menu field is also set 
to NULL because Windows CE supports menus through the command bar and com- 
mand bands controls. 

The hbinstance parameter is the same instance handle that was passed to the 
program. Creating windows is one place where that instance handle, saved at the 
start of the routine, comes in handy. The final parameter is a pointer that can be 
used to pass data from the CreateWindow call to the window procedure during the 
WM_CREATE message. In this example, no additional data needs to be passed, so 
the parameter is set to NULL. 

If successful, the CreateWindow call returns the handle to the window just cre- 
ated, or it returns 0 if an error occurred during the function. That window handle is then 
used in the two statements (ShowWindow and UpdateWindow) just after the error- 
checking if statement. The ShowWindow function modifies the state of the window to 
conform with the state given in the nCmdShow parameter passed to WinMain. The 
UpdateWindow function forces Windows to send a WM_PAINT message to the win- 
dow that has just been created. 

That completes the InitApp function. At this point, the application’s main win- 
dow has been created and updated. So even before we have entered the message 
loop, messages have been sent to the main window’s window procedure. It’s about 
time to look at this part of the program. 


MainWndProc 

You spend most of your programming time with the window procedure when you’re 
writing a Windows program. WinMain contains mainly initialization and cleanup code 
that, for the most part, is boilerplate. The window procedure, on the other hand, is 
the core of the program, the place where the actions of the program’s windows cre- 
ate the personality of the program. 


LRESULT CALLBACK MainWndProc(HWND hWnd, UINT wMsg, WPARAM wParam, 

LPARAM 1Param) { 

INT 7; 

// 

// Search message list to see if we need to handle this 

// message. If in list, call procedure. 

// 

for (i = 0; i < dim(MainMessages); i++) { 

if (wMsg == MainMessages[i].Code) 
return (*MainMessages[i].Fxn)(hWnd, wMsg, wParam, 1]Param); 
} 
return DefWindowProc(hWnd, wMsg, wParam, 1Param); 
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All window procedures, regardless of their window class, are declared with the 
same parameters. The LRESULT return type is actually just a long (a long is a 32-bit 
value under Windows) but is typed this way to provide a level of indirection between 
the source code and the machine. While you can easily look into the include files to 
determine the real type of variables that are used in Windows programming, this can 
cause problems when you're attempting to move your code across platforms. Though 
it can be useful to know the size of a variable type for memory-use calculations, there 
is no good reason, and there are plenty of bad ones, not to use the type definitions 
provided by windows.h. 

The CALLBACK type definition specifies that this function is an external entry 
point into the EXE, necessary because Windows calls this procedure directly, and that 
the parameters will be put in a Pascal-like right-to-left push onto the program stack, 
which is the reverse of the standard C-language method. The reason for using the 
Pascal language stack frame for external entry points goes back to the very earliest 
days of Windows development. The use of a fixed-size, Pascal stack frame meant that 
the called procedure cleaned up the stack instead of leaving it for the caller to do. 
This reduced the code size of Windows and its bundled accessory programs suffi- 
ciently so that the early Microsoft developers thought it was a good move. 

The first of the parameters passed to the window procedure is the window handle, 
which is useful when you need to define the specific instance of the window. The wMsg 
parameter indicates the message being sent to the window. This isn’t the MSG struc- 
ture used in the message loop in WinMain, but a simple, unsigned integer containing 
the message value. The remaining two parameters, wParam and /Param, are used to 
pass message-specific data to the window procedure. The names wParam and lParam 
come to us from the Win16 days, when the wParam was a 16-bit value and /Param 
was a 32-bit value. In Windows CE, as in other Win32 operating systems, both the 
wParam and [Param parameters are 32 bits wide. 

It’s in the window procedure that my programming style differs significantly from 
most Windows programs written without the help of a class library such as MFC. For 
almost all of my programs, the window procedure is identical to the one shown above. 
Before continuing, I repeat: this program structure isn’t specific to Windows CE. I use 
this style for all my Windows applications, whether they are for Windows 3.1, Win- 
dows 95, Windows NT, or Windows CE. 

This style reduces the window procedure to a simple table look-up function. 
The idea is to scan the MainMessages table defined early in the C file for the mes- 
sage value in one of the entries. If the message is found, the associated procedure 
is then called, passing the original parameters to the procedure processing the 
message. If no match is found for the message, the DefWindowProc function is called. 
DefWindowProc is a Windows function that provides a default action for all messages 
in the system, which frees a Windows program from having to process every mes- 
sage being passed to a window. 
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The message table associates message values with a procedure to process it. The 
table is listed below: 


// Message dispatch table for MainWindowProc 
const struct decodeUINT MainMessages[] = { 
WM_CREATE, DoCreateMain, 
WM_PAINT, DoPaintMain, 
WM_HIBERNATE, DoHibernateMain, 
WM_DESTROY, DoDestroyMain, 
}; 

The table is defined as a constant, not just as good programming practice but 
also because it’s helpful for memory conservation. Since Windows CE programs can 
be executed in place in ROM, data that doesn’t change should be marked constant. 
This allows the Windows CE program loader to leave such constant data in ROM 
instead of loading a copy into RAM so that it can be modified later by the program. 

The table itself is an array of a simple two-element structure. The first entry is 
the message value, followed by a pointer to the function that processes the message. 
While the functions could be named anything, I’m using a consistent structure through- 
out the book to help you keep track of them. The names are composed of a Do pre- 
fix (as a bow to object-oriented practice), followed by the message name and a suffix 
indicating the window class associated with the table. So, DoCreateMain is the name 
of the function that processes WM_CREATE messages for the main window of the 
program. 


DoCreateMain 

The WM_CREATE message is the first message sent to a window. WM_CREATE is 
unique among messages in that Windows sends it while processing the CreateWindow 
function, and therefore the window has yet to be completely created. This is a good 
place in the code to perform any data initialization for the window. But since the 
window is still being created, some Windows functions, such as GetWindowRect, used 
to query the size and position of the window, return inaccurate values. For our pur- 
poses, the procedure shown in the following code performs only one function: it 
creates a command bar for the window. 


LRESULT DoCreateMain (HWND hWnd, UINT wMsg, WPARAM wParam, 
LPARAM 1Param) { 
HWND hwndCB; 


// Create a command bar. 
hwndCB = CommandBar_Create (hInst, hWnd, IDC_CMDBAR); 


// Add exit button to command bar. 


CommandBar_AddAdornments (hwndCB, @, Q); 
return @; 
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Because Windows CE windows don’t support standard menus attached to win- 
dows, a command bar is necessary for menus. While HelloCE doesn’t have a menu, 
it does require a Close button, also provided by the command bar, so the program 
can be terminated by the user. For this reason, the simplest form of command bar, 
one with only a Close button, is created. You create the command bar by calling 
CommandBar_Create and passing the program’s instance handle, the handle to the 
window, and a constant that will be used to identify this specific command bar. (This 
constant can be any integer value as long as it is unique among the other child win- 
dows in the window.) Once you’ve created the command bar, you add a Close but- 
ton by calling CommandBar_AddAdornments. Since all we want to do is perform 
the default action for this function, the parameters passed are basic: the command 
bar handle and two zeros. That completes the processing of the WM_CREATE mes- 
sage. I’ll examine the command bar in depth in Chapter 5. 


DoPaintMain 

Painting the window, and therefore processing the WM_PAINT message, is one of 
the critical functions of any Windows program. As a program processes the WM_PAINT 
message, the look of the window is achieved. Aside from painting the default back- 
ground with the brush you specified when you registered the window class, Win- 
dows provides no help for processing this message. In HelloCE, the task of the 
DoPaintMain procedure is to display one line of text in the center of the window. 


LRESULT DoPaintMain (HWND hWnd, UINT wMsg, WPARAM wParam, 
LPARAM 1Param) { 
PAINTSTRUCT ps; 
RECT rect; 
HDC hdc; 


// Adjust the size of the client rect to take into account 

// the command bar height. 

GetClientRect (hWnd, &rect); 

rect.top += CommandBar_Height (GetDlgItem (hWnd, IDC_CMDBAR)); 


hdc = BeginPaint (hWnd, &ps); 
Drawlext (hdc, TEXT ("Hello Windows CE!"), -1, &rect, 
DT_CENTER | DT_VCENTER | DT_SINGLELINE); 


EndPaint (hWnd, &ps); 
return @; 
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Before the drawing can be performed, the routine must determine the size of the 
window. In a Windows program, a standard window is divided into two areas, the 
nonclient area and the client area. A window’s title bar and its sizing border commonly 
comprise the nonclient area of a window, and Windows is responsible for drawing it. 
The client area is the interior part of the window, and the application is responsible for 
drawing that. An application determines the size and location of the client area by call- 
ing the GetClientRect function. The function returns a RECT structure that contains left, 
top, right, and bottom elements that delineate the boundaries of the client rectangle. 
The advantage of the client vs. nonclient area concept is that an application doesn’t 
have to account for drawing such standard elements of a window as the title bar. 

When you’re computing the size of the client area, you must remember that 
the command bar resides in the client area of the window. So, even though the 
GetClientRect function works identically in Windows CE as in other versions of Win- 
dows, the application needs to compensate for the height of the command bar, which 
is always placed across the top of the window. Windows CE gives you a convenient 
function, CommandBar_Height, which returns the height of the command bar and 
can be used in conjunction with the GetClientRect call to get the true client area of 
the window that needs to be drawn by the application. 

Other versions of Windows supply a series of WM_NCxxx messages that en- 
able your applications to take over the drawing of the nonclient area. In Windows 
CE, windows seldom have title bars and at the present time, none of them have a 
sizing border. Because there’s so little nonclient area, the Windows CE developers 
decided not to expose the nonclient messages. 

All drawing performed in a WM_PAINT message must be enclosed by two func- 
tions, BeginPaint and EndPaint. The BeginPaint function returns an HDC, or handle 
to a device context. A device context is a logical representation of a physical display 
device such as a video screen or a printer. Windows programs never modify the dis- 
play hardware directly. Instead, Windows isolates the program from the specifics of 
the hardware with, among other tools, device contexts. 

BeginPaint also fills in a PAINTSTRUCT structure that contains a number of useful 
parameters. 


typedef struct tagPAINTSTRUCT { 
HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[32]; 
} PAINTSTRUCT; 
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The hdc field is the same handle that’s returned by the BeginPaint function. The 
fErase field indicates whether the background of the window needs to be redrawn by 
the window procedure. The rcPaint field is a RECT structure that defines the client 
area that needs repainting. HelloCE ignores this field and assumes that the entire client 
window needs repainting for every WM_PAINT message, but this field is quite handy 
when performance is an issue because only a part of the window might need repaint- 
ing. Windows actually prevents repainting outside of the rcPaint rectangle even when 
a program attempts to do so. The other fields in the structure, fRestore, fIncUpdate, and 
rebReserved, are used internally by Windows and can be ignored by the application. 

The only painting that takes place in HelloCE occurs in one line of text in the 
window. To do the painting, HelloCE calls the DrawText function. I cover the details 
of DrawText in the next chapter, but if you look at the function it’s probably obvious 
to you that this call draws the string “Hello Windows CE” on the window. After 
DrawText returns, EndPaint is called to inform Windows that the program has 
completed its update of the window. 

Calling EndPaint also validates any area of the window you didn’t paint. Win- 
dows keeps a list of areas of a window that are invalid (areas that need to be re- 
drawn) and valid (areas that are up to date). By calling the BeginPaint and EndPaint 
pair, you tell Windows that you’ve taken care of any invalid areas in your window, 
whether or not you’ve actually drawn anything in the window. In fact, you must call 
BeginPaint and EndPaint, or validate the invalid areas of the window by other means, 
or Windows will simply continue to send WM_PAINT messages to the window until 
those invalid areas are validated. 


DoHibernateMain 

You need DoHibernateMain because the WM_HIBERNATE message, unique to Win- 
dows CE, should be handled by every Windows CE program. A WM_HIBERNATE 
message is sent to a window to instruct it to reduce its memory use to the absolute 
minimum. 


LRESULT DoHibernateMain (HWND hWnd, UINT wMsg, WPARAM wParam, 
LPARAM 1Param) { 


// If not the active window, destroy the cmd bar to save memory. 
if (GetActiveWindow () != hWnd) 
CommandBar_Destroy (GetDlgItem (hWnd, IDC_CMDBAR)); 


return @; 


In the case of HelloCE, the only real way to reduce memory use is to destroy 
the command bar control. This is done by means of a call to CommandBar_Destroy. 
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The only case in which one should not destroy the command bar is when the window 
is the active window, the window through which the user is interacting with the pro- 
gram at the current time. 

More complex Windows CE applications have a much more elaborate procedure 
for handling the WM_HIBERNATE messages. Applications should free up as much 
memory and system resources as possible without losing currently unsaved data. In 
a choice between performance and lower memory use, an application is better reac- 
tivating slowly after a WM_HIBERNATE message than it is consuming more memory. 


DoActivateMain 

While the WM_ACTIVATE message is common to all Windows platforms, it takes on 
new significance for Windows CE applications because among its duties is to indi- 
cate that the window should restore any data structures or window controls that were 
freed by a WM_HIBERNATE message. 


LRESULT DoActivateMain (HWND hWnd, UINT wMsg, WPARAM wParam, 
LPARAM 1Param) { 
HWND hwndCB; 


// If activating and no command bar, create it. 
if ((LOWORD (wParam) != WA_INACTIVE) && 
(GetDlgItem (hWnd, IDC_CMDBAR) == 0)) { 


// Create a command bar. 
hwndCB = CommandBar_Create (hInst, hWnd, IDC_CMDBAR); 


// Add exit button to command bar. 
CommandBar_AddAdornments (hwndCB, @, Q): 


} 
return Q; 


The lower word of the wParam parameter is a flag that tells why the 
WM_ACTIVATE message was sent to the window. The flag can be one of three val- 
ues: WA_INACTIVE, indicating that the window is being deactivated after being the 
active window; WA_ACTIVE, indicating that the window is about to become the ac- 
tive window; and WA_CLICKACTIVE, indicating that the window is about to become 
the active window after having been clicked on by the user. 

HelloCE processes this message by checking to see whether the window remains 
active and whether the command bar no longer exists. If both conditions are true, the 
command bar is re-created using the same calls used for the WM_CREATE message. 
The GetDigitem function is convenient because it returns the handle of a child window 
of another window using its window ID. Remember that when the command bar, a 
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child of HelloCE’s main window, was created, I used an ID of IDC_CMDBAR (defined 
in HelloCE.h). That ID value is passed to GetDigitem to get the command bar window 
handle. However, if the command bar window doesn’t exist, the value returned is 0, 
indicating that HelloCE needs to re-create the command bar. 


DoDestroyMain 

The final message that HelloCE must process is the WM_DESTROY message sent when 
a window is about to be destroyed. Because this window is the main window of the 
application, the application should terminate when the window is destroyed. To make 
a WM_QUIT message in the message queue. The one parameter of this function is 
the return code value that will be passed back to the application in the wParam pa- 
rameter of the WM_QUIT message. 


LRESULT DoDestroyMain (HWND hWnd, UINT wMsg, WPARAM wParam, 
LPARAM 1Param) { 
PostQuitMessage (Q); 
return Q; 


Notice that the DoDestroyMain function doesn’t destroy the command bar con- 
trol created in DoCreateMain. Since the command bar is a child window of the main 
window, it’s automatically destroyed when its parent window is destroyed. 

As I’ve mentioned, when the message loop sees a WM_QUIT message, it exits 
the loop. The WinMain function then calls TermInstance, which in the case of HelloCE, 
does nothing but return. WinMain then returns, terminating the program. 


Running HelloCE 

After you’ve entered the program into Visual C++ and built it, it can be executed by 
a double-tap on the HelloCE icon. The program displays the Hello Windows CE text in 
the middle of an empty window, as shown in Figure 1-4. Figure 1-5 shows HelloCE 
running on a Palm-size PC. The command bar is placed by Windows CE across the 
top of the window. Tapping on the Close button on the command bar causes Win- 
dows CE to send a WM_CLOSE message to the window. Although HelloCE doesn’t 
explicitly process the WM_CLOSE message, the DefWindowProc procedure enables 
default processing by destroying the main window. As the window is being destroyed, 
a WM_DESTROY message is sent, which causes PostQuitMessage to be called. 
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Hello Windows CE! 


Hello Window's CE! 


Figure 1-5. 7he HelloCE window on a Palm-size PC. 


As I said, HelloCE is a very basic Windows CE program but it does gives you a 
skeleton of a Windows CE application upon which you can build. If you look at 
HelloCE.EXE using Explorer, the program is represented by a generic icon. When 
HelloCE is running, the button on the task bar representing HelloCE has no icon dis- 
played next to the text. How to add a program’s icon as well as how the DrawText 
function works are a couple of the topics I’ll address in the next few chapters. 


33 


Chapter 2 


Drawing 
on the Screen 


In Chapter 1, the example program HelloCE had one task: to display a line of text on 
the screen. Displaying that line took only one call to DrawText with Windows CE 
taking care of such details as the font and its color, the positioning of the line of text 
inside the window, and so forth. Given the power of a graphical user interface (GUD, 
however, an application can do much more than simply print a line of text on the 
screen. It can craft the look of the display down to the most minute of details. 

Over the life of the Microsoft Windows operating system, the number of func- 
tions available for crafting these displays has expanded dramatically. With each suc- 
cessive version of Windows, functions have been added that extend the tools available 
to the programmer. As functions were added, the old ones remained so that even if 
a function had been superseded by a new function old programs would continue to 
run on the newer versions of Windows. The approach in which function after func- 
tion is piled on while the old functions are retained for backward compatibility was 
discontinued with the initial version of Windows CE. Because of the requirement to 
produce a smaller version of Windows, the CE team took a hard look at the Win32 
API and replicated only the functions absolutely required by applications written for 
the Windows CE target market. 

One of the areas of the Win32 API hardest hit by this reduction was graphical 
functions. Not that you now lack the functions to do the job—it’s just that the high 
degree of redundancy led to some major pruning of the Win32 graphical functions. 
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An added challenge for the programmer is that different Windows CE platforms have 
subtly different sets of supported APIs. One of the ways in which Windows CE graphics 
support differs from that of its desktop cousins is that Windows CE doesn’t support 
the different mapping modes available under other implementations of Windows. 
Instead, the Windows CE device contexts are always set to the MM_TEXT mapping 
mode. Coordinate transformations are also not supported under Windows CE. While 
these features can be quite useful for some types of applications, such as desktop 
publishing, their necessity in the Windows CE environment of small portable devices 
isn’t as clear. Fortunately, as Windows CE matures we can expect more and more of 
the basic Win32 API to be supported. 

So when you’re reading about the functions and techniques used in this chap- 
ter, remember that some might not be supported on all platforms. So that a pro- 
gram can determine what functions are supported, Windows has always had the 
GetDeviceCaps function, which returns the capabilities of the current graphic device. 
Throughout this chapter, I'll refer to GetDeviceCaps when determining what functions 
are supported on a given device. 

This chapter, like the other chapters in Part I of this book, reviews the drawing 
features supported by Windows CE. One of the most important facts to remember is 
that while Windows CE doesn’t support the full Win32 graphics API, its rapid evolu- 
tion has resulted in it supporting some of the newest functions in Win32—-some so 
new that you might not be familiar with them. This chapter shows you the functions 
you can use and how to work around the areas where certain functions aren’t sup- 
ported under Windows CE. 


PAINTING BASICS 
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Historically, Windows has been subdivided into three main components: the ker- 
nel, which handles the process and memory management, User, which handles the 
windowing interface and controls; and the Graphics Device Interface, or GDI, which 
performs the low-level drawing. In Windows CE, User and GDI are combined into 
the Graphics Windowing and Event handler, or GWE. At times, you might hear a 
Windows CE programmer talk about the GWE. The GWE is nothing really new—just 
a different packaging of standard Windows parts. In this book, I usually refer to the 
graphics portion of the GWE under its old name, GDI, to be consistent with standard 
Windows programming terminology. 

But whether you’re programming for Windows CE or Windows 98 or Windows NT, 
there is more to drawing than simply handling the WM_PAINT message. It’s helpful 
to understand just when and why a WM_PAINT message is sent to a window. 
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Valid and Invalid Regions 


When for some reason an area of a window is exposed to the user, that area, or re- 
gion, as it’s referred to in Windows, is marked invalid. When no other messages are 
waiting in an application’s message queue and the application’s window contains an 
invalid region, Windows sends a WM_PAINT message to the window. As mentioned 
in Chapter 1, any drawing performed in response to a WM_PAINT message is couched 
in calls to BeginPaint and EndPaint. BeginPaint actually performs a number of ac- 
tions. It marks the invalid region as valid, and it computes the clipping region. The 
clipping region is the area to which the painting action will be limited. BeginPaint 
then sends a WM_ERASEBACKGROUND message, if needed, to redraw the back- 
ground, and it hides the caret—the text entry cursor—if it’s displayed. Finally 
BeginPaint retrieves the handle to the display device context so that it can be used 
by the application. The EndPaint function releases the device context and redisplays 
the caret if necessary. If no other action is performed by a WM_PAINT procedure, you 
must at least call BeginPaint and EndPaint if only to mark the invalid region as valid. 

Alternatively, you can call to ValidateRect to blindly validate the region. But no 
drawing can take place in that case because an application must have a handle to the 
device context before it can draw anything in the window. 

Often an application needs to force a repaint of its window. An application should 
never post or send a WM_PAINT message to itself or to another window. Instead, 
you do the following: 


BOOL InvalidateRect (HWND hWnd, const RECT *]pRect, BOOL bErase); 


Notice that InvalidateRect doesn’t require a handle to the window’s device context, 
only to the window handle itself. The /pbRect parameter is the area of the window to 
be invalidated. This value can be NULL if the entire window is to be invalidated. The 
bErase parameter indicates whether the background of the window should be redrawn 
during the BeginPaint call as mentioned above. Note that unlike other versions of 
Windows, Windows CE requires that the )Wnd parameter be a valid window handle. 


Device Contexts 


A device context, often referred to simply as a DC, is a tool that Windows uses to 
manage access to the display and printer, although for the purposes of this chapter 
Pll be talking only about the display. Also, unless otherwise mentioned, the explana- 
tion that follows applies to Windows in general and isn’t specific to Windows CE. 

Windows applications never write directly to the screen. Instead, they request 
a handle to a display device context for the appropriate window, and then using the 
handle, draw to the device context. Windows then arbitrates and manages getting 
the pixels from the DC to the screen. 
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BeginPaint, which should only be called in a WM_PAINT message, returns a 
handle to the display DC for the window. An application usually performs its draw- 
ing to the screen during the WM_PAINT messages. Windows treats painting as a low- 
priority task, which is appropriate since having painting at a higher priority would 
result in a flood of paint messages for every little change to the display. Allowing an 
application to complete all its pending business by processing all waiting messages 
results in all the invalid regions being painted efficiently at once. Users don’t notice 
the minor delays caused by the low priority of the WM_PAINT messages. 

Of course, there are times when painting must be immediate. An example of 
such a time might be when a word processor needs to display a character immedi- 
ately after its key is pressed. To draw outside a WM_PAINT message, the handle to 
the DC can be obtained using this: 


HDC GetDC (HWND hWnd); 


GetDC returns a handle to the DC for the client portion of the window. Drawing can 
then be performed anywhere within the client area of the window because this pro- 
cess isn’t like processing inside a WM_PAINT message; there’s no clipping to restrict 
you from drawing in an invalid region. 

Windows CE 2.1 supports another function that can be used to receive the 
DC. It is 


HDC GetDCEx (HWND hWnd, HRGN hrgnClip, DWORD flags); 


GetDCEx allows you to have more control over the device context returned. The new 
parameter, brgncClip lets you define the clipping region, which limits drawing to 
that region of the DC. The flags parameter lets you specify how the DC acts as you 
draw on it. Windows CE doesn’t support the following flags: DCX_PARENTCLIP, 
DCX_NORESETATTRS, DCX_LOCKWINDOWUPDATE, and DCX_VALIDATE. 

After the drawing has been completed, a call must be made to release the de- 
vice context: 


int ReleaseDC (HWND hWnd, HDC hDC); 


Device contexts are a shared resource, and therefore an application must not hold 
the DC for any longer than necessary. 

While GetDC is used to draw inside the client area, sometimes an application 
needs access to the nonclient areas of a window, such as the title bar. To retrieve a 
DC for the entire window, make the following call: 


HDC GetWindowDC (HWND hWnd); 


As before, the matching call after drawing has been completed for GetWindowDC 
is ReleaseDC. | 
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The DC functions under Windows CE are identical to the device context func- 
tions under Windows 98 and Windows NT. This should be expected because DCs 
are the core of the Windows drawing philosophy. Changes to this area of the API 
would result in major incompatibilities between Windows CE applications and their 
desktop counterparts. 


WRITING TEXT 


In Chapter 1, the HelloCE example displayed a line of text using a call to DrawText. 
That line from the example is shown here: 


Drawlext (hdc, TEXT ("Hello Windows CE!"), -1, &rect, 
DT_CENTER | DT_VCENTER | DT_SINGLELINE); 


DrawText is a fairly high-level function that allows a program to display text 
while having Windows deal with most of the details. The first few parameters of 
DrawText are almost self-explanatory. The handle of the device context being used 
is passed, along with the text to display couched in a TEXT macro, which declares 
the string as a Unicode string necessary for Windows CE. The third parameter is the 
number of characters to print, or as is the case here, a —1 indicating that the string 
being passed is null terminated and Windows should compute the length. 

The fourth parameter is a pointer to a rect structure that specifies the formatting 
rectangle for the text. DrawText uses this rectangle as a basis for formatting the text to 
be printed. How the text is formatted depends on the function’s last parameter, the 
formatting flags. These flags specify how the text is to be placed within the formatting 
rectangle, or in the case of the DT_CALCRECT flag, the flags have DrawText compute 
the dimensions of the text that is to be printed. DrawText even formats multiple lines 
with line breaks automatically computed. In the case of HelloCE, the flags specify that 
the text should be centered horizontally (DT_CENTER), and centered vertically 
(DT_VCENTER). The DT_VCENTER flag works only on single lines of text, so the final 
parameter, DT_SINGLELINE, specifies that the text shouldn’t be flowed across multiple 
lines if the rectangle isn’t wide enough to display the entire string. 


Device Context Attributes 


What I haven’t mentioned yet about HelloCE’s use of DrawText is the large number of 
assumptions the program makes about the DC configuration when displaying the text. 
Drawing in a Windows device context takes a large number of parameters, such as fore- 
ground and background color and how the text should be drawn over the background 
as well as the font of the text. Instead of specifying all these parameters for each draw- 
ing call, the device context keeps track of the current settings, referred to as attributes, 
and uses them as appropriate for each call to draw to the device context. 
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Foreground and background colors 
The most obvious of the text attributes are the foreground and background color. Two 
functions, SetTextColor and GetTextColor, allow a program to set and retrieve the 
current color. These functions work well with both four-color gray-scale screens as 
well as the color screens supported by Windows CE devices. 

To determine how many colors a device supports, use GetDeviceCaps as men- 
tioned previously. The prototype for this function is the following: 


int GetDeviceCaps (HDC hdc, int nIndex); 


You need the handle to the DC being queried because different DCs have dif- 
ferent capabilities. For example, a printer DC differs from a display DC. The second 
parameter indicates the capability being queried. In the case of returning the colors 
available on the device, the NUMCOLORS value returns the number of colors as long 
as the device supports 256 colors or fewer. Beyond that, the returned value for 
NUMCOLORS is —1 and the colors can be returned using the BITSPIXEL value, which 
returns the number of bits used to represent each pixel. This value can be converted 
to the number of colors by raising 2 to the power of the BITSPIXEL returned value, 
as in the following code sample: 


nNumColors = GetDeviceCaps (hdc, NUMCOLORS); 
if (nNumColors == -1) 
nNumColors = 1 << GetDeviceCaps (hdc, BITSPIXEL); 


Drawing mode 

Another attribute that affects text output is the background mode. When letters are 
drawn on the device context, the system draws the letters themselves in the foreground 
color. The space between the letters is another matter. If the background mode is set 
to opaque, the space is drawn with the current background color. But if the back- 
ground mode is set to transparent, the space between the letters is left in whatever 
state it was in before the text was drawn. While this might not seem like a big differ- 
ence, imagine a window background filled with a drawing or graph. If text is written 
over the top of the graph and the background mode is set to opaque, the area around 
the text will be filled, and the background color will overwrite the graph. If the back- 
ground mode is transparent, the text will appear as if it had been placed on the graph, 
and the graph will show through between the letters of the text. 


The TextDemo Example Program 
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The TextDemo program, shown in Figure 2-1, demonstrates the relationships among 
the text color, the background color, and the background mode. 
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Figure 2-1. Zhe TextDemo program. (continued) 
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Figure 2-1. continued 
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(continued) 
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Figure 2-1. continued 
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(continued) 
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Figure 2-1. continued 
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Figure 2-2. TextDemo shows how the text color, background color, and background 
mode relate. 


The first four lines are drawn using the transparent mode. The second four are 
drawn using the opaque mode. The text color is set from black to white, so that each 
line drawn uses a different color, while at the same time the background color is set 
from white to black. In transparent mode, the background color is irrelevant be- 
cause it isn’t used; but in opaque mode, the background color is readily apparent 
on each line. 


Fonts 


If the ability to set the foreground and background colors were all the flexibility that 
Windows provided, we might as well be back in the days of MS-DOS and character 
attributes. Arguably, the most dramatic change from MS-DOS is Windows’ ability to 
change the font used to display text. All Windows operating systems are built around 
the concept of WYSIWYG—what you see is what you get—and changeable fonts are 
a major tool used to achieve that goal. 

Two types of fonts appear in all Windows operating systems—raster and 
TrueType. Raster fonts are stored as bitmaps, small pixel by pixel images, one for each 
character in the font. Raster fonts are easy to store and use but have one major prob- 
lem: they don’t scale well. Just as a small picture looks grainy when blown up to a 
much larger size, raster fonts begin to look blocky as they are scaled to larger and 
larger font sizes. 
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TrueType fonts solve the scaling problem. Instead of being stored as images, each 
TrueType character is stored as a description of how to draw the character. The font 
engine, which is the part of Windows that draws characters on the screen, then takes 
the description and draws it on the screen in any size needed. TrueType font support 
was introduced with Windows 3.1 but was only added to the Windows CE line in Win- 
dows CE 2.0. Even under Windows CE 2.0, though, some devices such as the origi- 
nal Palm-size PC, don’t support TrueType fonts. A Windows CE system can support 
either TrueType or raster fonts, but not both. Fortunately, the programming interface 
is the same for both raster and TrueType fonts, relieving Windows developers from 
worrying about the font technology in all but the most exacting of applications. 

The font functions under Windows CE closely track the same functions under 
other versions of Windows. Let’s look at the functions used in the life of a font, from 
creation through selection in a DC and finally to deletion of the font. How to query 
the current font as well as enumerate the available fonts is also covered in the fol- 
lowing sections. 


Creating a font 
Before an application is able to use a font other than the default font, the font must 
be created and then selected into the device context. Any text drawn in a DC after 
the new font has been selected into the DC will then use the new font. 

Creating a font in Windows CE can be accomplished this way: 


HFONT CreateFontIndirect (const LOGFONT *Ip]f);. 


This function is passed a pointer to a LOGFONT structure that must be filled 
with the description of the font you want. 


typedef struct tagLOGFONT { 
LONG 1fHeight; 
LONG 1fWidth; 
LONG 1fEscapement; 
LONG 1fOrientation; 
~ LONG 1fWeight; 
BYTE Ifitalic; 
BYTE 1fUnderline; 
BYTE 1fStrikeOut; 
BYTE 1fCharSet; 
BYTE 1fOutPrecision; 
BYTE I1fClipPrecision; 
BYTE 1fQuality; 
BYTE 1fPitchAndFamily; 
TCHAR 1fFaceName[LLF_FACESIZE]; 
} LOGFONT; 
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The /fHeight field specifies the height of the font in device units. If this field 
is 0, the font manager returns the default font size for the font family requested. For 
most applications, however, you want to create a font of a particular point size. The 
following equation can be used to convert point size to the /fHeight field: 


lfHeight = -1 * (PointSize * GetDeviceCaps (hdc, LOGPIXELSY) / 72); 


Here, GetDeviceCaps is passed a LOGPIXELSY field instructing it to return the 
number of logical pixels per inch in the vertical direction. The 72 is the number of 
points (a typesetting unit of measure) per inch. 

The /fWidth field specifies the average character width. Since the height of a 
font is more important than its width, most programs set this value to 0. This tells 
the font manager to compute the proper width based on the height of the font. The 
lfEscapement and IfOrientation fields specify the angle in tenths of degrees of the base 
line of the text and the x-axis. The /fWeight field specifies the boldness of the font 
from 0 through 1000, with 400 being a normal font and 700 being bold. The next three 
fields specify whether the font is to be italic, underline, or strikeout. 

The /pCharSet field specifies the character set you have chosen. This field is more 
important in international releases of software, where it can be used to request a 
specific language’s character set. The /fOutPrecision field can be used to specify 
how closely Windows matches your requested font. Among a number of flags avail- 
able, a OUT_TT_ONLY_PRECIS flag specifies that the font created must be a 
TrueType font. The //ClipPrecision field specifies how Windows should clip char- 
acters that are partially outside the region being displayed. The /fQuality field is set 
to either DEFAULT_QUALITY or DRAFT_QUALITY, which gives Windows permis- 
sion to synthesize a font that, while more closely matching the other requested fields, 
might look less polished. 

The /fPitchAndFamily field specifies the family of the font you want. This field 
is handy when you're requesting a family such as Swiss, that features proportional 
fonts without serifs, or a family such as Roman, that features proportional fonts with 
serifs, but you don’t have a specific font in mind. You can also use this field to specify 
simply a proportional or a monospaced font and allow Windows to determine which 
font matches the other specified characteristics passed into the LOGFONT struc- 
ture. Finally, the /fFaceName field can be used to specify the typeface name of a 
specific font. 

When CreateFontIndirect is called with a filled LOGFONT structure, Windows 
creates a logical font that best matches the characteristics provided. To use the font 
however, the final step of selecting the font into a device context must be made. 
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Selecting a font into a device context 
You select a font into a DC by using the following function: 


HGDIOBJ SelectObiect (HDC hdc, HGDIOBJ hgdiobi): 


This function is used for more than just setting the default font; you use this func- 
tion to select other GDI objects, as we shall soon see. The function returns the previ- 
ously selected object Gin our case the previously selected font), which should be saved 
so that it can be selected back into the DC when we're finished with the new font. The 
line of code looks like the following: 


hOldFont = SelectObject (hdc, hFont); 


When the logical font is selected, the system determines the closest match to the 
logical font from the fonts available in the system. For devices without TrueType fonts, 
this match could be a fair amount off from the specified parameters. Because of this, 
never assume that just because you’ve requested a particular font, the font returned 
exactly matches the one you requested. For example, the height of the font you 
asked for might not be the height of the font that’s selected into the device context. 


Querying a font’s characteristics 
To determine the characteristics of the font that is selected into a device context, a 
call to 


BOOL GetTextMetrics (HDC hdc, LPTEXTMETRIC Iptm); 


returns the characteristics of that font. A TEXTMETRIC structure is returned with the 
information and is defined as 


typedef struct tagTEXTMETRIC { 
LONG tmHeight; 
LONG tmAscent; 
LONG tmDescent; 
LONG tmInternalLeading; 
LONG tmExternalLeading; 
LONG tmAveCharWidth; 
LONG tmMaxCharWidth; 
LONG tmWeight; 
LONG tmOverhang; 
LONG tmDigitizedAspectx; 
LONG tmDigitizedAspecty; 
char tmFirstChar; 
char tmLastChar; 
char tmDefaultChar; 
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char tmBreakChar; 
BYTE tmIitalic; 
BYTE tmUnderlined; 
BYTE tmStruckOut; 
BYTE tmPitchAndFamily; 
BYTE tmCharSet; 

} TEXTMETRIC; 


The TEXTMETRIC structure contains a number of the fields we saw in the 
LOGFONT structure but this time the values listed in TEXTMETRIC are the values of 


the font that’s selected into the device context. Figure 2-3 shows the relationship of 
some of the fields to actual characters. 


tmHeight 
tminternalLeading © rrnenntrbberrnene 


tmAscent 


tmDescent 


Figure 2-3. Fields from the TEXTMETRIC structure and how they relate to a font. 


Aside from determining whether you really got the font you wanted, the 
GetTextmetrics call has another valuable purpose—determining the height of the font. 
Recall that in TextDemo, the height of the line was computed using a call to DrawText. 
While that method is convenient, it tends to be slow. You can use the TEXTMETRIC 
data to compute this height in a much more straightforward manner. By adding the 
tmHeight field, which is the height of the characters, to the tmExternalLeading field, 
which is the distance between the bottom pixel of one row and the top pixel of the 
next row of characters, you can determine the vertical distance between the baselines 
of two lines of text. 
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Destroying a font 

Like other GDI resources, fonts must be destroyed after the program has finished using 
them. Failure to delete fonts before terminating a program causes what’s known as a 
resource leak—an orphaned graphic resource that’s taking up valuable memory but 
that’s no longer owned by an application. 

To destroy a font, first deselect it from any device contexts it has been selected 
into. You do this by calling SelectObject; the font passed is the font that was returned 
by the original SelectObject call made to select the font. After the font has been dese- 
lected, a call to 


BOOL DeleteObject (HGDIOBJ hObject); 


(with hObject containing the font handle) deletes the font from the system. 

As you can see from this process, font management is no small matter in Win- 
dows. The many parameters of the LOGFONT structure might look daunting, but they 
give an application tremendous power to specify a font exactly. 

One problem when dealing with fonts is determining just what types of fonts 
are available on a specific device. Windows CE devices come with a set of standard 
fonts, but a specific system might have been loaded with additional fonts by either 
the manufacturer or the user. Fortunately, Windows provides a method for enumer- 
ating all the available fonts in a system. 


Enumerating fonts 
To determine what fonts are available on a system, Windows provides this function: 


int EnumFontFamilies (HDC hdc, LPCTSTR lpszFamily, 
FONTENUMPROC 1pEnumFontFamProc, LPARAM 1Param); 


This function lets you list all the font families as well as each font within a fam- 
ily. The first parameter is the obligatory handle to the device context. The second 
parameter is a string to the name of the family to enumerate. If this parameter is null, 
the function enumerates each of the available families. 

The third parameter is something different—a pointer to a function provided 
by the application. The function is a callback function that Windows calls once for 
each font being enumerated. The final parameter, /Param, is a generic parameter that 
can be used by the application. This value is passed unmodified to the application’s 
callback procedure. 7 

While the name of the callback function can be anything, the prototype of the 
callback must match the declaration: 


int CALLBACK EnumFontFamProc (LOGFONT *lpelf, TEXTMETRIC *1pntm, 
DWORD FontType, LPARAM 1Param); 
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The first parameter passed back to the callback function is a pointer to a 
LOGFONT structure describing the font being enumerated. The second parameter, a 


pointer to a textmetric structure, further describes the font. The font type parameter 
indicates whether the font is a raster or TrueType font. 


The FontList Example Program 


The FontList program, shown in Figure 2-4, uses the EnumFontFamilies function in 
two ways to enumerate all fonts in the system. 


Figure 2-4. The FontList program enumerates all fonts in the system. 


(continued) 
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Figure 2-4. continued 
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Figure 2-4. continued 


56 


Chapter 2 Drawing on the Screen 


(continued) 


57 


Ss 


Figure 2-4. continued 
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Figure 2-4. continued 
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Enumerating the different fonts begins when the application is processing the 
WM_CREATE message in OnCreateMain. Here, EnumFontFamilies is called with the 
FontFamily field set to NULL so that each family will be enumerated. The callback 
function is FontFamilyCallback, where the name of the font family is copied into an 
array of strings. 

The remainder of the work is performed during the processing of the 
WM_PAINT message. The OnPaintMain function begins with the standard litany 
of getting the size of the area below the command bar and calling BeginPaint, which 
returns the handle to the device context of the window. GetTextMetrics is then called 
to compute the row height of the default font. A loop is then entered in which 
EnumerateFontFamilies is called for each family name that had been stored during 
the enumeration process in OnCreateMain. The callback process for this callback 
sequence is somewhat more complex than the code we’ve seen so far. 

The PaintSingleFontFamily callback procedure, used in the enumeration of 
the individual fonts, employs the /Param parameter to retrieve a pointer to a 
PAINTFONTINFO structure defined in FontList.h. This structure contains the current 
vertical drawing position as well as the handle to the device context. By using the 
lParam pointer, FontList avoids having to declare global variables to communicate 
with the callback procedure. 

The callback procedure next creates the font using the pointer to LOGFONT 
that was passed to the callback procedure. The new font is then selected into the device 
context, while the handle to the previously selected font is retained in hOldFont. The 
point size of the enumerated font is computed using the inverse of the equation 
mentioned earlier in the chapter on page 49. The callback procedure then produces 
a line of text showing the name of the font family along with the point size of this 
particular font. Instead of using DrawText, the callback uses a different text output 
function: 


BOOL ExtTextOut (HDC hdc, int X, int Y, UINT fuOptions, 
const RECT *Iprc, LPCTSTR IpString, 
UINT cbCount, const int *1pDx); 
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The ExtTextOut function has a few advantages over DrawText in this situation. 
First, ExtTextOut tends to be faster for drawing single lines of text. Second, instead of 
formatting the text inside a rectangle, x and y starting coordinates are passed, speci- 
fying the upper left corner of the rectangle where the text will be drawn. The rect 
parameter that’s passed is used as a clipping rectangle, or if the background mode is 
opaque, the area where the background color is drawn. This rectangle parameter can 
be NULL if you don’t want any clipping or opaquing. The next two parameters are 
the text and the character count. The last parameter, ExtTextOut, allows an applica- 
tion to specify the horizontal distance between adjacent character cells. In our case, 
this parameter is set to NULL also, which results in the default separation between 
characters. 

Windows CE differs from other versions of Windows in having only these two 
text drawing functions for displaying text. Most of what you can do with the other 
text functions typically used in other versions of Windows, such as TextOut and 
TabbedTextOut, can be emulated using either DrawText or ExtTextOut. This is one 
of the areas in which Windows CE has broken with earlier versions of Windows, 
sacrificing backward compatibility to achieve a smaller operating system. 

After displaying the text, the function computes the height of the line of text 
just drawn using the combination of tmHeight and tmExternalLeading that was pro- 
vided in the passed TEXTMETRIC structure. The new font is then deselected using a 
second call to SelectObject, this time passing the handle to the font that was the origi- 
nal selected font. The new font is then deleted using DeleteObject. Finally, the call- 
back function returns a nonzero value to indicate to Windows that it is okay to make 
another call to the enumerate callback. 

Figure 2-5 shows the FontListing window. Notice that the font names are dis- 
played in that font and that each font has a specific set of available sizes. 


Family: MS Sans Serif 
MS Sans Serif Point: 


MS Sans Serf Pointl? 
Family: Courier New 
Courier New Point:10 


Courier New Point:12 


Family: Times New Roman 
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Times New Roman Point:11 
Times New Roman Point:14 


Times New Roman Point:15 
Times 
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Figure 2-5. The FontList window shows some of the available fonts 
for a Handbeld PC. 
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Unfinished business 

If you look closely at Figure 2-5, you’ll notice a problem with the display. The list of 
fonts just runs off the bottom edge of the FontList window. At this point in a book 
covering the desktop versions of Windows, the author might add a window style flag 
for a vertical scroll bar and a small amount of code, and magically, the program would 
have a scrollable window. But if you do that to a Windows CE main window, you 
end up with the look shown in Figure 2-6. 


Family: MS Sans Serif 
MS Sans Serf Point:9 
MS Sans Serif Pointl2 


Family: Courier New 
Courier New Point: 10 


Courier New Point:12 


Family: Times New Roman 
Times New Roman Point:10 


Times New Roman Point:11 
Times New Roman Point:14 


Times New Roman Point:15 
Times New Roman._Point:20. 


Figure 2-6. The FontList window with a scrollbar attached to the main window. 


Notice how the scroll bar extends past the right side of the command bar up to 
the top of the window. The scroll bar should stop below the command bar and the 
command bar should extend to the right edge of the window. The problem is that 
the command bar lies in the client area of the window, and the default scroll bar style 
provided by all Windows operating systems places the scroll bar outside the client 
area, in the nonclient space along the edge of the window. The solution to this prob- 
lem involves creating a child window inside our main window and letting it do the 
scrolling. But since I'll provide a complete explanation of child windows in Chap- 
ter 4, Pll hold off describing how to properly implement a scroll bar until then. 


BITMAPS 


Bitmaps are graphical objects that can be used to create, draw, manipulate, and re- 
trieve images in a device context. Bitmaps are everywhere within Windows, from the 
little Windows logo on the Start button to the Close button on the command bar. Think 
of a bitmap as a picture composed of an array of pixels that can be painted onto the 
screen. Like any picture, a bitmap has height and width. It also has a method for 
determining what color or colors it uses. Finally, a bitmap has an array of bits that 
describe each pixel in the bitmap. 
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Historically, bitmaps under Windows have been divided into two types; device 
dependent bitmaps (DDBs) and device independent bitmaps (DIBs). DDBs are bitmaps 
that are tied to the characteristics of a specific DC and can’t easily be rendered on 
DCs with different characteristics. DIBs, on the other hand, are independent of any 
device and therefore must carry around enough information so that they can be ren- 
dered accurately on any device. 

Windows CE contains many of the bitmap functions available in other versions 
of Windows. The differences include a new four-color bitmap format not supported 
anywhere but on Windows CE and a different method for manipulating DIBs. 


Device Dependent Bitmaps 
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A device dependent bitmap can be created with this function: 


HBITMAP CreateBitmap (int nWidth, int nHeight, UINT cPlanes, 
UINT cBitsPerPel, CONST VOID *lIpvBits); 


The nWidth and nHeight parameters indicate the dimensions of the bitmap. The 
cPlanes parameter is an historical artifact from the days when display hardware imple- 
mented each color within a pixel in a different hardware plane. For Windows CE, 
this parameter must be set to 1. The cBitspPerPel parameter indicates the number of 
bits used to describe each pixel. The number of colors is 2 to the power of the 
cBitspPerPel parameter. Under Windows CE, the allowable values are 1, 2, 4, 8, 16, 
and 24. As I said, the four-color bitmap is unique to Windows CE and isn’t supported 
under other Windows platforms, including the Windows CE emulator that runs on 
top of Windows NT. 

The final parameter is a pointer to the bits of the bitmap. Under Windows CE, 
the bits are always arranged in a packed pixel format; that is, each pixel is stored as 
a series of bits within a byte, with the next pixel starting immediately after the first. 
The first pixel in the array of bits is the pixel located in the upper left corner of the 
bitmap. The bits continue across the top row of the bitmap, then across the second 
row, and so on. Each row of the bitmap must be double-word (4-byte) aligned. If 
any pad bytes are required at the end of a row to align the start of the next row, they 
should be set to 0. Figure 2-7 illustrates this scheme, showing a 126-by-64 pixel bitmap 
with 8 bits per pixel. 

The function 


HBITMAP CreateCompatibleBitmap (HDC hdc, int nWidth, int nHeight); 


creates a bitmap whose format is compatible with the device context passed to the 
function. So, if the device context is a four-color DC, the resulting bitmap is a four- 
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color bitmap as well. This function comes in handy when you’re manipulating im- 
ages on the screen because it makes it easy to produce a blank bitmap that’s directly 
color compatible with the screen. 


Byte 
Offset Row - 0 ; 
0 0 


7936 «63 
Figure 2-7. Layout of bytes within a bitmap. 


Device Independent Bitmaps 


The fundamental difference between DIBs and their device dependent cousins is that 
the image stored in a DIB comes with its own color information. Almost every bitmap 
file since Windows 3.0, which used the files with the BMP extension, contains infor- 
mation that can be directly matched with the information needed to create a DIB in 
Windows. 

In the early days of Windows, it was a rite of passage for a programmer to write 
a routine that manually read a DIB file and converted the data to a bitmap. These 
days, the same arduous task can be accomplished with the following function, unique 
to Windows CE: 


HBITMAP SHLoadDIBitmap (LPCTSTR szFileName) ; 


It loads a bitmap directly from a bitmap file and provides a handle to the bitmap. In 
Windows NT and Windows 98, the same process can be accomplished with Loadimage 
using the LR_LOADFROMEFILE flag, but this flag isn’t supported under the Windows CE 
implementation of LoadImage. 
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While Windows CE makes it easy to load a bitmap file, sometimes you must read what 
is on the screen, manipulate it, and redraw the image back to the screen. This is an- 
other case in which DIBs are better than DDBs. While the bits of a device dependent 
bitmap are obtainable, the format of the buffer is directly dependent on the screen 
format. By using a DIB, or more precisely, something called a DIB section, your pro- 
gram can read the bitmap into a buffer that has a predefined format without worry- 
ing about the format of the display device. 

While Windows has a number of DIB creation functions that have been added 
over the years since Windows 3.0, Windows CE carries over only one DIB section 
function from Windows NT and Windows 98. Here it is: 


HBITMAP CreateDIBSection (HDC hdc, const BITMAPINFO «pbmi, 
UINT iUsage, void *ppvBits, 
HANDLE hSection, DWORD dwOffset); 


Because it’s a rather late addition to the Win32 API, DIB sections might be new to 
Windows programmers. DIB Sections were invented to improve the performance of 
applications on Windows NT that directly manipulated bitmaps. In short, a DIB sec- 
tion allows a programmer to select a DIB in a device context while still maintaining 
direct access to the bits that compose the bitmap. To achieve this, a DIB section as- 
sociates a memory DC with a buffer that also contains the bits of that DC. Because 
the image is mapped to a DC, other graphics calls can be made to modify the image. 
At the same time, the raw bits of the DC, in DIB format, are available for direct ma- 
nipulation. While the improved performance is all well and good on NT, the relevance 
to the Windows CE programmer is the ease in which an application can work with 
bitmaps and manipulate their contents. 

The parameters of this call lead off with the pointer to a BITMAPINFO struc- 
ture. This structure describes the layout and color composition of a device indepen- 
dent bitmap and is a combination of a BITMAPINFOHEADER structure and an array 
of RGBQUAD values that represent the palette of colors used by the bitmap. 

The BITMAPINFOHEADER structure is defined as the following: 


typedef struct tagBITMAPINFOHEADER{ 
DWORD biSize; 
LONG biWidth; 
LONG biHeight; 
WORD biPlanes; 
WORD biBitCount; 
DWORD biCompression; 
DWORD biSizelImage; 
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LONG biXPelsPerMeter; 

LOG biYPelsPerMeter; 

DWORD biClrUsed; 

DWORD biCIrImportant; 
} BITMAPINFOHEADER; 


As you can see, this structure contains much more information than just the pa- 
rameters passed to CreateBitmap. The first field is the size of the structure and must 
be filled in by the calling program to differentiate this structure from the similar 
BITMAPCOREINFOHEADER structure that’s a holdover from the OS/2 presentation 
manager. The biWidth, biHeight, biPlanes, and biBitCount fields are similar to their 
like-named parameters to the CreateBitmap call—with one exception. The sign of 
the biHeight field specifies the organization of the bit array. If biHeight is negative, 
the bit array is organized in a top-down format, as is CreateBitmap. If biHeight is 
positive, the array is organized in a bottom-up format, in which the bottom row of 
the bitmap is defined by the first bits in the array. As with the CreateBitmap call, the 
biPlanes field must be set to 1. 

The biCompression field specifies the compression method used in the bit ar- 
ray. Under Windows CE, the only allowable setting for this field is BI_RGB, indicat- 
ing that the buffer isn’t compressed. The biSizelmage parameter is used to indicate 
the size of the bit array; when used with BI_LRGB, however, the biSizeIlmage field can 
be set to 0, meaning the array size is computed using the dimensions and bits per 
pixel information provided in the BITMAPINFOHEADER structure. 

The bixXPelsPerMeter and biYPelsPerMeter fields provide information to accu- 
rately scale the image. For CreateDIBSection, however, these parameters can be set 
to 0. The biClrUsed parameter specifies the number of colors in the palette that are 
actually used. In a 256-color image, the palette will have 256 entries, but the bitmap 
itself might need only 100 or so distinct colors. This field helps the palette manager, 
the part of the Windows that manages color matching, to match the colors in the system 
palette with the colors required by the bitmap. The biClrImportant field further de- 
fines the colors that are really required as opposed to those that are used. For most 
color bitmaps, these two fields are set to 0, indicating that all colors are used and that 
all colors are important. 

As I mentioned above, an array of RGBQUAD structures immediately follows 
the BITMAPINFOHEADER structure. The RGBQUAD structure is defined as follows: 


typedef struct tagRGBQUAD { /* rgbq */ 
BYTE rgbBlue; 
BYTE rgbGreen; 
BYTE rgbRed; 
BYTE rgbReserved; 
} RGBQUAD; 
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This structure allows for 256 shades of red, green, and blue. While almost any 
shade of color can be created using this structure, the color that’s actually rendered 
on the device will, of course, be limited by what the device can display. 

The array of RGBQUAD structures, taken as a whole, describe the palette of 
the DIB. The palette is the list of colors in the bitmap. If a bitmap has a palette, each 
entry in the bitmap array contains not colors, but an index into the palette that con- 
tains the color for that pixel. While redundant on a monochrome bitmap, the palette 
is quite important when rendering color bitmaps on color devices. For example a 256 
color bitmap has one byte for each pixel, but that byte points to a 24 bit value that 
represents equal parts red, green, and blue colors. So, while a 256-color bitmap can 
only contain 256 distinct colors, each of those colors can be one of 16 million colors 
rendered using the 24-bit palette entry. For convenience in a 32-bit world, each pal- 
ette entry, while containing only 24 bits of color information, is padded out to a 32- 
bit wide entry—hence the name of the data type: RGBQUAD. 

Of the remaining four CreateDIBSection parameters, only two are used under 
Windows CE. The iUsage parameter indicates how the colors in the palette are repre- 
sented. For Windows CE, this field must be set to DIB_RGB_COLORS. The ppvBits 
parameter is a pointer to a variable that receives the pointer to the bitmap bits that 
compose the bitmap image. The final two parameters, bSection and dwOffset, aren’t 
supported under Windows CE and must be set to 0. In other versions of Windows, 
they allow the bitmap bits to be specified by a memory mapped file. While Windows 
CE does support memory mapped files, they aren’t supported by CreateDIBSection. 


Drawing Bitmaps 
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Creating and loading bitmaps is all well and good, but there’s not much point to it 
unless the bitmaps you create can be rendered on the screen. Drawing a bitmap isn’t 
as straightforward as you might think. Before a bitmap can be drawn in a screen DC, 
it must be selected into a DC and then copied over to the screen device context. While 
this process sounds convoluted, there is rhyme to this reason. 

_ The process of selecting a bitmap into a device context is similar to selecting a 
logical font into a device context; it converts the ideal to the actual. Just as Windows 
finds the best possible match to a requested font, the bitmap selection process must 
match the available colors of the device to the colors requested by a bitmap. Only 
after this is done can the bitmap be rendered on the screen. To help with this inter- 
mediate step, Windows provides a shadow type of DC, a memory device context. 

To create a memory device context, use this function: 


HDC CreateCompatibleDC (HDC hdc); 
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This function creates a memory DC that’s compatible with the current screen DC. Once 

created, the source bitmap is selected into this memory DC using the same SelectObject 

function you used to select in a logical font. Finally, the bitmap is copied from the 

memory DC to the screen DC using one of the blit functions, BitBlt or StretchBit. 
The workhorse of bitmap functions is the following: 


BOOL BitBIlt (HDC hdcDest, int nxXDest, int nYDest, int nWidth, 
int nHeight, HDC hdcSrc, int nXSrc, int nYSrc, 
DWORD dwRop); 


Fundamentally, the BitBlt function, pronounced bit blit, is just a fancy memcopy 
function, but since it operates on device contexts, not memory, it’s something far more 
special. The first parameter is a handle to the destination device context—the DC to 
which the bitmap is to be copied. The next four parameters specify the location and 
size of the destination rectangle where the bitmap is to end up. The next three pa- 
rameters specify the handle to the source device context and the location within that 
DC of the upper left corner of the source image. 

The final parameter, dwRop, specifies how the image is to be copied from the 
source to the destination device contexts. The ROP code defines how the source bitmap 
and the current destination are combined to produce the final image. The ROP code 
for a simple copy of the source image is SRCCOPY. The ROP code for combining the 
source image with the current destination is SRCPAINT. Copying a logically inverted 
image, essentially a negative of the source image, is accomplished using SRCINVERT. 
Some ROP codes also combine the currently selected brush into the equation to 
compute the resulting image. A large number of ROP codes are available, too many 
for me to cover here. For a complete list, check out the Windows CE programming 
documentation. 

The following code fragment sums up how to paint a bitmap: 


// Create a DC that matches the device. 
hdcMem = CreateCompatibleDC (hdc); 


// Select the bitmap into the compatible device context. 
hOldSel = SelectObject (hdcMem, hBitmap); 


// Get the bitmap dimensions from the bitmap. 

GetObject (hBitmap, sizeof (BITMAP), &bmp); 

// Copy the bitmap image from the memory DC to the screen DC. 

BitBIt (hdc, rect.left, rect.top, bmp.bmWidth, bmp.bmHeight, 
hdcMem, @, @, SRCCOPY); 


(continued) 
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// Restore original bitmap selection and destroy the memory DC. 
SelectObject (hdcMem, h0O1dSel); 
DeleteDC (hdcMem) ; | 

The memory device context is created and the bitmap to be painted is selected 
into that DC. Since you might not have stored the dimensions of the bitmap to be 
painted, the routine makes a call to GetObject. GetObject returns information about a 
graphics object, in this case, a bitmap. Information about fonts and other graphic 
objects can be queried using this useful function. Next, BitBit is used to copy the bitmap 
into the screen DC. To clean up, the bitmap is deselected from the memory device 
context and the memory DC is deleted using DeleteDC. Don’t confuse DeleteDC with 
ReleaseDC, which is used to free a display DC. DeleteDC should be paired only with 
CreateCompatibleDC and ReleaseDC should be paired only with GetDC or 
GetWindowDC. 

Instead of merely copying the bitmap, stretch or shrink it using this function: 


BOOL StretchBlit (HDC hdcDest, int nXOriginDest, int nYOriginDest, 
int nWidthDest, int nHeightDest, HDC hdcSrc, 
int nXOriginSrc, int nYOriginSrc, int nWidthSrc, 
int nHeightSrc, DWORD dwRop); 


The parameters in StretchBit are the same as those used in BitBit, with the ex- 
ception that now the width and height of the source image can be specified. Here 
again, the ROP codes specify how the source and destination are combined to pro- 
duce the final image. | 

Windows CE 2.0 added a new, and quite handy, bitmap function. It is 


BOOL TransparentImage (HDC hdcDest, LONG DstX, LONG DstY, LONG DstCx, 
LONG DstCy, HANDLE hSrc, LONG SrcX, LONG SrcyY, 
LONG SrcCx, LONG SrcCy, COLORREF TransparentColor); 


This function is similar to StretchBlt with two very important exceptions. First, you 
can specify a color in the bitmap to be the transparent color. When the bitmap is copied 
to the destination, the pixels in the bitmap that are the transparent color are not cop- 
ied. The second difference is that the bSrc parameter can either be a device context 
or a handle to a bitmap, which allows you to bypass the requirement to select the 
source image into a device context before rendering it on the screen. 

As in other versions of Windows, Windows CE supports two other blit func- 
tions: PatBit and MaskBit. The PatBlt function combines the currently selected brush 
with the current image in the destination DC to produce the resulting image. I cover 
brushes later in this chapter. The MaskBit function is similar to BitBlt but encompasses 
a masking image that provides the ability to draw only a portion of the source image 
onto the destination DC. 
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LINES AND SHAPES 


One of the areas in which Windows CE provides substantially less functionality than 
other versions of Windows is in the primitive line-drawing and shape-drawing func- 
tions. Gone are the Chord, Arc, and Pie functions that created complex circular shapes. 
Gone too is the concept of current point. Other versions of Windows track a current 
point, which is then used as the starting point for the next drawing command. So 
drawing a series of connected lines and curves by calling MoveTo to move the cur- 
rent point followed by calls to LineTo, ArcTo, PolyBezierTo and so forth is no longer 
possible. But even with the loss of a number of graphic functions, Windows CE still 
provides the essential functions necessary to draw lines and shapes. 


Lines 
Drawing one or more lines is as simple as a call to 


BOOL Polyline (HDC hdc, const POINT *lppt, int cPoints); 


The second parameter is a pointer to an array of POINT structures that are defined as 
the following: 


typedef struct tagPOINT { 
LONG x; 
LONG y; 

} POINT; 


Each x and y combination describes a pixel from the upper left corner of the 
screen. The third parameter is the number of point structures in the array. So to draw 
a line from (0, 0) to (50, 100), the code would look like this: 


POINTS pts[2]; 


pts[0].x = Q; 
ptsLO].y = @; 
pts[1].x = 50; 
pts[l].y = 100; 


PolyLine (hdc, &pts, 2); 


Just as in the early text examples, this code fragment makes a number of as- 
sumptions about the default state of the device context. For example, just what does 
the line drawn between (0,0) and (50, 100) look like? What is its width and its color, 
and is it a solid line? All versions of Windows, including Windows CE, allow these 
parameters to be specified. 
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The tool for specifying the appearance of lines and the outline of shapes is called, 
appropriately enough, a pen. A pen is another GDI object and, like the others de- 
scribed in this chapter, is created, selected into a device context, used, deselected, 
and then destroyed. Among other stock GDI objects, stock pens can be retrieved using 
the following code: 


HGDIOBJ GetStockObject (int fnObject); 


All versions of Windows provide three stock pens, each 1 pixel wide. The stock 
pens come in 3 colors: white, black, and null. Using GetStockObject, the call to re- 
trieve one of those pens employs the parameters WHITE_PEN, BLACK_PEN, and 
NULL_PEN respectively. Unlike standard graphic objects created by applications, stock 
objects should never be deleted by the application. Instead, the application should 
simply deselect the pen from the device context when it’s no longer needed. 

To create a custom pen under Windows, two functions are available. The first 
is this: 


HPEN CreatePen ( int fnPenStyle, int nWidth, COLORREF crColor); 


The fnPenStyle parameter specifies the appearance of the line to be drawn. For ex- 
ample, the PS_DASH flag can be used to create a dashed line. The n Width parameter 
specifies the width of the pen. Finally, the crColor parameter specifies the color of 
the pen. The crColor parameter is typed as COLORREF, which under Windows CE 
2.0 is an RGB value. The RGB macro is as follows: 


COLORREF RGB (BYTE bRed, BYTE bGreen, BYTE bBlue); 

So to create a solid red pen, the code would look like this: 

hPen = CreatePen (PS_SOLID, 1, RGB (Oxff, 0, @)); 
The other pen creation function is the following: 

HPEN CreatePenIndirect (const LOGPEN *Iplgpn); 

where the logical pen structure LOGPEN is defined as 


typedef struct tagLOGPEN { 
UINT lopnStyle; 
POINT lopnWidth; 
COLORREF lopnColor; 

} LOGPEN; 


CreatePenIndirect provides the same parameters to Windows, in a different form. To 
create the same 1-pixel-wide red pen with CreatePenIndirect, the code would look 
like this: 
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LOGPEN Ip; 
HPEN hPen; 


Ip. lopnStyle = PS_SOLID; 
lTp.lopnWidth.x = 1; 

lp. lopnWidth. 13 

lp. lopnColor RGB (@xff, 0, Q); 
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hPen = CreatePenIndirect (&lp); 


Windows CE devices don’t support complex pens such as wide (more than 
one pixel wide), dashed lines. To determine what’s supported, our old friend 
GetDeviceCaps comes into play, taking LINECAPS as the second parameter. Refer to 
the Windows CE documentation for the different flags returned by this call. 


Shapes 


Lines are useful but Windows also provides functions to draw shapes, both filled and 
unfilled. Here, Windows CE does a good job supporting most of the functions famil- 
iar to Windows programmers. The Rectangle, RoundRect, Ellipse, and Polygon func- 
tions are all supported. 


Brushes 

Before I can talk about shapes such as rectangles and ellipses I need to describe another 
GDI object that ’'ve only mentioned briefly before now, called a brush. A brush is a 
small 8-by-8 bitmap used to fill shapes. It’s also used by Windows to fill the back- 
ground of a client window. Windows CE provides a number of stock brushes and 
also the ability to create a brush from an application-defined pattern. A number of 
stock brushes, each a solid color, can be retrieved using GetStockObject. Among the 
brushes available is one for each of the grays of a four grayscale display: white, light 
gray, dark gray, and black. 

To create solid color brushes, the function to call is the following: 


HBRUSH CreateSolidBrush (COLORREF crColor); 


This function isn’t really necessary when you’re writing an application for a four-color 
Windows CE device because those four solid brushes can be retrieved with the 
GetStockObject call. For higher color devices however, the crColor parameter can be 
generated using the RGB macro. 

| To create custom pattern brushes, Windows CE supports the Win32 function: 


HBRUSH CreateDIBPatternBrushPt (const void *IpPackedDIB, 
UINT iUsage); 
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The first parameter to this function is a pointer to a DIB in packed format. This means 
that the pointer points to a buffer that contains a BITMAPINFO structure immediately 
followed by the bits in the bitmap. Remember that a BITMAPINFO structure is ac- 
tually a BITMAPINFOHEADER structure followed by a palette in RGBQUAD for- 
mat, so the buffer contains everything necessary to create a DIB—that is, bitmap 
information, a palette, and the bits to the bitmap. The second parameter must be 
set to DIB_RGB_COLORS for Windows CE applications. This setting indicates that 
the palette specified contains RGBQUAD values in each entry. The complimentary 
flag, DIB_PAL_COLORS, used in other versions of Windows isn’t supported in 
Windows CE. | 

The CreateDIBPatternBrushPt function is more important under Windows CE 
because the hatched brushes, supplied under other versions of Windows by the 
CreateHachBrush function, aren’t supported under Windows CE. Hatched brushes 
are brushes composed of any combination of horizontal, vertical, or diagonal lines. 
Ironically, they’re particularly useful with grayscale displays because you can use them 
to accentuate different areas of a chart with different hatch patterns. These brushes, 
however, can be reproduced by using CreateDIBPatternBrushPt and the proper 
bitmap patterns. The Shapes code example, later in the chapter, demonstrates a method 
for creating hatched brushes under Windows CE. 

By default, the brush origin will be in the upper left corner of the window. This 
isn’t always what you want. Take, for example, a bar graph where the bar filled with 
a hatched brush fills a rectangle from (100, 100) to (125, 220). Since this rectangle 
isn’t divisible by 8 (brushes being 8 by 8 pixels square), the upper left corner of the 
bar will be filled with a partial brush that might not look pleasing to the eye. 

To avoid this situation, you can move the origin of the brush so that each shape 
can be drawn with the brush aligned correctly in the corner of the shape to be filled. 
The function available for this remedy is the following: 


BOOL SetBrushOrgEx (HDC hdc, int nXOrg, int nYOrg, LPPOINT Ippt); 


The nXOrg and nYOrg parameters allow the origin to be set between 0 and 7 so that 
you can position the origin anywhere in the 8-by-8 space of the brush. The /ppt pa- 
rameter is filled with the previous origin of the brush so that you can restore the pre- 
vious origin if necessary. 


Rectangles 
The rectangle function draws either a filled or a hollow rectangle; the function is de- 
fined as the following: 


BOOL Rectangle (HDC hdc, int nLeftRect, int nTopRect, 
int nRightRect, int nBottomRect); 
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The function uses the currently selected pen to draw the outline of the rectangle and 
the current brush to fill the interior. To draw a hollow rectangle, select the null brush 
into the device context before calling Rectangle. 

The actual pixels drawn for the border are important to understand. Say we’re 
drawing a 5-by-7 rectangle at 0, 0. The function call would look like this: 


Rectangle (0, 0, 5, 7); 


Assuming that the selected pen was 1 pixel wide, the resulting rectangle would look 
like the one shown in Figure 2-8. 
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Figure 2-8. Expanded view of a rectangle drawn with the Rectangle function. 


Notice how the right edge of the drawn rectangle is actually drawn in column 
4 and that the bottom edge is drawn on row 6. This is standard Windows practice. 
The rectangle is drawn inside the right and bottom boundary specified for the Rect- 
angle function. If the selected pen is wider than one pixel, the right and bottom edges 
are drawn with the pen centered on the bounding rectangle. (Other versions of Win- 
dows support the PS_INSIDEFRAME pen style that forces the rectangle to be drawn 
inside the frame regardless of the pen width.) 


Circles and ellipses 
Circles and ellipses can be drawn with this function: 


BOOL Ellipse (HDC hdc, int nLeftRect, int nTopRect, 
int nRightRect, int nBottomRect); 


The ellipse is drawn using the rectangle passed as a bounding rectangle, as shown in 
Figure 2-9. As with the Rectangle function, while the interior of the ellipse is filled 
with the current brush, the outline is drawn with the current pen. | 
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Figure 2-9. The ellipse is drawn within the bounding rectangle passed to the Ellipse 
function. 


Round rectangles 
The RoundRect function, 


BOOL RoundRect (HDC hdc, int nLeftRect, int nTopRect, 
int nRightRect, int nBottomRect, 
int nWidth, int nHeight); 


draws a rectangle with rounded corners. The roundedness of the corners is defined 
by the last two parameters that specify the width and height of the ellipse used to 
round the corners, as shown in Figure 2-10. Specifying the ellipse height and width 
enables your program to draw identically symmetrical rounded corners. Shortening 
the ellipse height flattens out the sides of the rectangle, while shortening the width 
of the ellipse flattens the top and bottom of the rectangle. 
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Figure 2-10. 7he height and width of the ellipse define the round corners of the 
rectangle drawn by RoundRect. 


Polygons 
Finally, the Polygon function, 


BOOL Polygon (HDC hdc, const POINT *1lpPoints, int nCount); 
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draws a many-sided shape. The second parameter is a pointer to an array of point 
structures defining the points that delineate the polygon. The resulting shape has one 
more side than the number of points because the function automatically completes 
the last line of the polygon by connecting the last point with the first. Under Win- 
dows CE 1.0, this function is limited to producing convex polygons. 


The Shapes Example Program 


The Shapes program, shown in Figure 2-11, demonstrates a number of these func- 
tions. In Shapes, five figures are drawn, each filled with a different brush. 


Figure 2-11. 7he Shapes program. (continued) 
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(continued) 
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Figure 2-11. continued 
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(continued) 
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Figure 2-11. continued 
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filled with a brush created with the CreateDIBPatternBrushPt. The creation of this 
brush is segregated into a function called MyCreateHatchBrush that mimics the Create- 
HatchBrush function not available under Windows CE. To create the hatched brushes, 
a black and white bitmap is built by filling in a bitmap structure and setting the bits 
to form the hatch patterns. The bitmap itself is the 8-by-8 bitmap specified by Create- 
DIBPatternBrushPt. Since the bitmap is monochrome, its total size, including the 
palette and header, is only around 100 bytes. Notice, however, that since each scan 
line of a bitmap must be double-word aligned, the last three bytes of each one-byte 
scan line are left unused. 

Finally the program completes the painting by writing two lines of text into the 
lower rectangle. The text further demonstrate the difference between the opaque and 
transparent drawing modes of the system. In this case, the opaque mode of drawing 
the text might be a better match for the situation because the hatched lines tend to 
obscure letters drawn in transparent mode. A view of the Shapes window is shown 
in Figure 2-12. 
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Figure 2-12. The Shapes example demonstrates drawing different filled shapes. 


To keep things simple, the Shapes example assumes that it’s running on at least 
a 480-pixel-wide display. To properly display the same shapes on a Palm-size PC 
requires a few minor changes to the coordinates used to position the shapes displayed. 

I have barely scratched the surface of the abilities of the Windows CE GDI por- 
tion of GWE. The goal of this chapter wasn’t to provide total presentation of all as- 
pects of GDI programming. Instead, I wanted to demonstrate the methods available 
for basic drawing and text support under Windows CE. In other chapters in the book, 
I extend some of the techniques touched on in this chapter. I talk about these new 
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techniques and newly introduced functions at the point, generally, where I demonstrate 
how to use them in code. To further your knowledge, I recommend Programming 
Windows 95, by Charles Petzold (Microsoft Press, 1996), as the best source for learning 
about the Windows GDI. 

Now that we’ve looked at output, it’s time to turn our attention to the input side 
of the system, the keyboard and touch panel. 


Chapter 3 


Input: Keyboard, 
Stylus, and Menus 


Traditionally, Microsoft Windows platforms have allowed users two methods of in- 
put: the keyboard and the mouse. Windows CE continues this tradition, but replaces 
the mouse with a stylus and touch screen. Programmatically, the change is minor 
because the messages from the stylus are mapped to the mouse messages used in 
other versions of Windows. A more subtle but also more important change from ver- 
sions of Windows that run on PCs is that a system running Windows CE might have 
either a tiny keyboard or no keyboard at all. This makes the stylus input that much 
more important for Windows CE systems. 


THE KEYBOARD 


While keyboards play a lesser role in Windows CE, they’re still the best means of 
entering large volumes of information. Even on systems without a physical keyboard 
such as the Palm-size PC, soft keyboards—controls that simulate keyboards on a touch 
screen—will most likely be available to the user. Given this, proper handling of key- 
board input is critical to all but the most specialized of Windows CE applications. While 
Pll talk at length about soft keyboards later in the book, one point should be made 
here. To the application, input from a soft keyboard is no different from input from a 
traditional “hard” keyboard. 
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Input Focus 


Under Windows operating systems, only one window at a time has the input focus. 
The focus window receives all keyboard input until it loses focus to another window. 
The system assigns the keyboard focus using a number of rules but most often the 
focus window is the current active window. The active window, you'll recall, is the 
top-level window, the one with which the user is currently interacting. With rare 
exceptions, the active window also sits at the top of the Z-order; that is, it’s drawn on 
top of all other windows in the system. The user can change the active window by 
pressing Alt-Esc to switch between programs or by tapping on another top-level 
window’s button on the task bar. The focus window is either the active window or 
one of its child windows. 

Under Windows, a program can determine which window has the input focus 
by calling 


HWND GetFocus (void); 
The focus can be changed to another window by calling 
HWND SetFocus (HWND hWnd); 


Under Windows CE, the target window of SetFocus is limited. The window being given 
the focus by SetFocus must have been created by the thread calling SetFocus. An 
exception to this rule occurs if the window losing focus is related to the window gaining 
focus by a parent/child or sibling relationship; in this case, the focus can be changed 
even if the windows were created by different threads. 

When a window loses focus, Windows sends a WM_KILLFOCUS message to 
that window informing it of its new state. The wParam parameter contains the handle 
of the window that will be gaining the focus. The window gaining focus receives a 
WM_SETFOCUS message. The wParam parameter of the WM_SETFOCUS message 
contains the handle of the window losing focus. 

Now for a bit of motherhood. Programs shouldn’t change the focus window 
without some input from the user. Otherwise, the user can easily become confused. 
A proper use of SetFocus is to set the input focus to a child window Gmore than likely 
a control) contained in the active window. In this case, a window would respond to 
the WM_SETFOCUS message by calling SetFocus with the handle of a child window 
contained in the window to which the program wants to direct keyboard messages. 


Keyboard Messages 


Windows CE practices the same keyboard message processing as its larger desktop 
relations with a few small exceptions, which I cover shortly. When a key is pressed, 
Windows sends a series of messages to the focus window, typically beginning with a 
WM_KEYDOWN message. If the key pressed represents a character such as letter or 
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number, Windows follows the WM_KEYDOWN with a WM_CHAR message. (Some 
keys, such as function keys and cursor keys don’t represent characters, so WM_CHAR 
messages aren’t sent in response to those keys. For those keys, a program must 
interpret the WM_KEYDOWN message to know when the keys are pressed.) When 
the key is released, Windows sends a WM_KEYUP message. If a key is held down 
long enough for the auto-repeat feature to kick in, multiple WM_KEYDOWN and 
WM_CHAR messages are sent for each auto-repeat until the key is released when 
the final WM_KEYUP message is sent. I used the word typically to qualify this 
process because if the Alt key is being held when another key is pressed, the mes- 
sages I’ve just described are replaced by WM_SYSKEYDOWN, WM_SYSCHAR, and 
WM_SYSKEYUP messages. 

For all of these messages, the generic parameters wParam and [Param are used 
in mostly the same manner. For WM_KEYxx and WM_SYSKEYxx messages, the 
wParam value contains the virtual key value, indicating the key being pressed. All 
versions of Windows provide a level of indirection between the keyboard hardware 
and applications by translating the scan codes returned by the keyboard into virtual 
key values. You see a list of the VK_xx values and their associated keys in Figure 3-1. 
While the table of virtual keys is extensive, not all keys listed in the table are present 
on Windows CE devices. For example, function keys, a mainstay on PC keyboards 
and listed in the virtual key table, aren’t present on most Windows CE keyboards. In 
fact, anumber of keys on a PC keyboard are left off the space-constrained Windows CE 
keyboards. A short list of the keys not typically used on Windows CE devices is pre- 
sented in Figure 3-2 on page 92. This list is meant to inform you that these keys might 
not exist, not to indicate that the keys never exist on Windows CE keyboards. 


VIRTUAL-KEY CODES 


Constant Value Keyboard Equivalent 
VK_LBUTTON 01 Stylus tap 
VK_RBUTTON 02 Mouse right button$ 
VK_CANCEL 03 Control-break processing 
VK_RBUTTON 04 Mouse middle button$ 
-- 05—07 Undefined 
VK_BACK 08 Backspace key 
VK_TAB 09 Tab key 
-- OA—OB Undefined 
VK_CLEAR OC Clear key 

Figure 3-1. Virtual key values in relation to the keys on the keyboard. (continued) 


Not all keys will be on all keyboards. 
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Figure 3-1. continued 


Constant 


VK_RETURN 
VK_SHIFT 
VK_CONTROL 
VK_MENU 
VK_CAPITAL 


VK_ESCAPE 
VK_SPACE 
VK_PRIOR 
VK_NEXT 
VK_END 
VK_HOME 
VK_LEFT 
VK_UP 
VK_RIGHT 
VK_DOWN 
VK_SELECT 


VK_EXECUTE 
VK_SNAPSHOT 
VK_INSERT 
VK_DELETE 
VK_HELP 
VK_0—-VK_9 
VK_A-VK_Z 
VK_LWIN 
VK_RWIN 


Value 


OE-—OF 


15-19 


1C—1F 


30-39 
3A—40 
41-5A 
5B 
5C 


Keyboard Equivalent 


Enter key 
Undefined 
Shift key 
Ctrl key 


Alt key 


Caps Lock key 

Reserved for Kanji systems 
Undefined 

Escape key 

Reserved for Kanji systems 
Spacebar 

Page Up key 

Page Down key 

End key 

Home key 

Left Arrow key 

Up Arrow key 

Right Arrow key 

Down Arrow key 

Select key 

Original equipment manufacturer (OEM)— 
specific 

Execute key 

Print Screen key for Windows 3.0 and later 
Insert * 

Delete? 

Help key 

0-9 keys 

Undefined 

A through Z keys 
Windows key 

Windows key * 


Constant 


VK_APPS 
VK_NUMPADO-9 
VK_MULTIPLY 
VK_ADD 
VK_SEPARATOR 
VK_SUBTRACT 
VK_DECIMAL 
VK_DIVIDE 
VK_F1-VK_F24 
VK_NUMLOCK 
VK_SCROLL 
VK_LSHIFT 
VK_RSHIFT 
VK_LCONTROL 
VK_RCONTROL 
VK_LMENU 
VK_RMENU 
VK_SEMICOLON 
VK_EQUAL 
VK_COMMA 
VK_HYPHEN 
VK_PERIOD 
VK_SLASH 
VK_BACKQUOTE 
VK_LBRACKET 
VK_BACKSLASH 
VK_RBRACKET 
VK_APOSTROPHE 


Value 


5D 
SE—5F 
60-69 
OA 

6B 

6C 

6D 

OE 

OF 
70-87 
88—8F 
90 

91 
92-9F 
AO 

Al 

A2 

A3 

A4 

A5 
AO-B9 
BA 
BB 

BC 
BD 
BE 

BF 

CO 
C1—DA 
DB 
DC 
DD 
DE 


Chapter 3 Input: Keyboard, Stylus, and Menus 


Keyboard Equivalent 


Undefined 

Numeric keypad 0-9 keys 
Numeric keypad Asterisk (*) key 
Numeric keypad Plus sign (+) key 
Separator key 

Numeric keypad Minus sign (—) key 
Numeric keypad Period (.) key 
Numeric keypad Slash mark (/) key 
F1—F24 * 

Unassigned 

Num Lock * 

Scroll Lock * 

Unassigned 

Left Shift? 

Right Shift? 

Left Control* 

Right Control* 

Left Alt? 

Right Alt? 

Unassigned 

; key 

= key 

, key 

- key 

. key 

/ key 

~ key 

Unassigned 

[ key 

\ key 

] key 

‘key 


(continued) 
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Figure 3-1. continued 


Constant Value Keyboard Equivalent 
VK_OFF DF Power button 
-- E5 Unassigned 

-- E6 OEM-specific 
-- E7-—E8 Unassigned 

-- E9—F5 OEM-specific 
VK_ATTN F6 

VK_CRSEL F7 

VK_EXSEL F8 

VK_EREOF F9 

VK_PLAY FA 

VK_ZOOM FB 

VK_NONAME FC 

VK_PA1 FD 

VK_OEM_CLEAR FE 


* Many Windows CE Systems don’t have this key. 
On some Windows CE systems, Delete is simulated with Shift-Backspace 
These constants can be used only with GetKeyState and GetAsyncKeyState. 


A +e s+ 


Mouse right and middle buttons are defined but are relevant only on a Windows CE system 
equipped with a mouse. 


For the WM_CHAR and WM_SYSCHAR messages, the wParam value contains 
the Unicode character represented by the key. Most often an application can simply 
look for WM_CHAR messages and ignore WM_KEYDOWN and WM_KEYUP. The 
WM_CHAR message allows for a second level of abstraction so that the application 
doesn’t have to worry about the up or down state of the keys and can concentrate on 
the characters being entered by means of the keyboard. 

The /Param value of any of these keyboard messages contains further informa- 
tion about the pressed key. The format of the [Param parameter is shown in Figure 3-3 
on the following page. 


InsertDelete (Many Windows CE keyboards use Shift-Backspace for this function.) 
Num LockPause 

Print Screen 

Scroll Lock 

Function Keys 

Windows Context Menu key 


Figure 3-2. Keys on a PC keyboard that are rarely on a Windows CE keyboard. 
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The low word, bits 0 through 15, contains the repeat count of the key. Often, 
keys on a Windows CE device can be pressed faster than Windows CE can send 
messages to the focus application. In these cases, the repeat count contains the num- 
ber of times the key has been pressed. Bit 29 contains the context flag. If the Alt key 
was being held down when the key was pressed, this bit will be set. Bit 30 contains 
the previous key state. If the key was previously down, this bit is set; otherwise it’s 0. 
Bit 30 can be used to determine whether the key message is the result of an auto- 
repeat sequence. Bit 31 indicates the transition state. If the key is in transition from 
down to up, Bit 31 is set. The Reserved field, bits 16 through 28, is used in the desk- 
top versions of Windows to indicate the key scan code. In almost all cases, Windows 
CE doesn’t support this field. However, on some of the newer Windows CE platforms 
where scan codes are necessary, this field does contain the scan code. You shouldn’t 
plan on the scan code field being available unless you know it’s supported on your 
specific platform. 


EPA MASAI ON es ie AMA 


sere fsezeeol 8 17/16 [15]14[13| 


Reserved Repeat count 


Context flag, set to 1 if Alt key down 
Previous key state, set to 1 if key previously down 
Transition state, set to 1 if key is being released 


Figure 3-3. The layout of the \Param value for key messages. 


One additional keyboard message, WM_DEADCHAR, can sometimes come into 
play. You send it when the pressed key represents a dead character, such as an um- 
laut, that you want to combine with a character to create a different character. In this 
case the WM_DEADCHAR message can be used to prevent the text entry point (the 
caret) from advancing to the next space until the second key is pressed so that you 
can complete the combined character. 

The WM_DEADCHAR message has always been present under Windows, but 
under Windows CE it takes on a somewhat larger role. With the internationalization 
of small consumer devices that run Windows CE, programmers should plan for, and 
if necessary use, the WM_DEADCHAR message that is so often necessary in foreign 
language systems. 


Keyboard Functions 


You will find useful a few other keyboard-state-determining functions for Windows 
applications. Among the keyboard functions, two are closely related but often con- 
fused: GetKeyState and GetAsyncKeyState. 
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GetKeyState, prototyped as 


SHORT GetKeyState (int nVirtKey); 


returns the up/down state of the shift keys, Ctrl, Alt, and Shift, and indicates whether 
any of these keys is in a toggled state. If the keyboard has two keys with the same 
function—for example, two Shift keys, one on each side of the keyboard—this 
function can also be used to differentiate which of them is being pressed. (Most key- 


boards have left and right Shift keys, and some include left and right Ctrl and Alt keys.) 


You pass to the function the virtual key code for the key being queried. If the 
high bit of the return value is set, the key is down. If the least significant bit of the 
return value is set, the key is in a toggled state; that is, it has been pressed an odd 
number of times since the system was started. The state returned is the state at the 
time the most recent message was read from the message queue, which isn’t neces- 
sarily the real-time state of the key. An interesting aside: notice that the virtual key 
label for the Alt key is VK_MENU, which relates to the windows convention that the 
Alt-shift key combination works in concert with other keys to access various menus 
from the keyboard. 

Note that the GetKeyState function is limited under Windows CE to querying 
the state of the shift keys. Under other versions of Windows, GetKeyState can deter- 
mine the state of every key on the keyboard. 

To determine the real-time state of a key, use 


SHORT GetAsyncKeyState (int vKey); 


As with GetKeyState, you pass to this function the virtual key code for the key being 
queried. The GetAsyncKeyState function returns a value subtly different from the one 
returned by GetKeyState. As with the GetKeyState function, the high bit of the return 
value is set while the key is being pressed. However, the least significant bit is then 
set if the key was pressed after a previous call to GetAsyncKeyState. Like GetKeyState, 
the GetAsyncKeyState function can distinguish the left and right Shift, Ctrl, and Alt 
keys. In addition, by passing the VK_LBUTTON virtual key value, GetAsyncKeyState 
determines whether the stylus is currently touching the screen. 
An application can simulate a keystroke using the keybd_event function: 


VOID keybd_event (BYTE bVk, BYTE bScan, DWORD dwFlags, 
DWORD dwExtralInfo); 


The first parameter is the virtual key code of the key to simulate. The bScan code 
should be set to NULL under Windows CE. The dwFlags parameter can have two 
possible flags: KEYEVENTF_KEYUP indicates that the call is to emulate a key up 
event while KEYEVENTF_SILENT indicates that the simulated key press won’t cause 
the standard keyboard click that you normally hear when you press a key. So, to 
fully simulate a key press, Reybd_event should be called twice, once without 
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KEYEVENTF_KEYUP to simulate a key down, then once again, this time with 
KEYEVENTF_KEYUP to simulate the key release. 

One final keyboard function, MapVirtualKey, translates virtual key codes to 
characters. MapVirtualKey in Windows CE doesn’t translate keyboard scan codes to 
and from virtual key codes, although it does so in other versions of Windows. The 
prototype of the function is the following: 


UINT MapVirtualKey (UINT uCode, UINT uMapType); 


Under Windows CE, the first parameter is the virtual key code to be translated while 
the second parameter, uMapType, must be set to 2. 


Testing for the keyboard 

To determine whether a keyboard is even present in the system, first call GetVersionEx 
to find out which version of Windows CE is running. All systems that run Windows 
CE 1.0 have a keyboard. When running under Windows CE 2.0 or later, call 


DWORD GetKeyboardStatus (VOID); 


This function returns the KBDI_LKEYBOARD_PRESENT flag if a hardware keyboard 
is present in the system. This function also returns a KBDILKEYBOARD_ENABLED 
flag if the keyboard is enabled. To disable the keyboard, a call can be made to 


BOOL EnableHardwareKeyboard (BOOL bEnable); 


with the bEnable flag set to FALSE. You might want to disable the keyboard in a sys- 
tem for which the keyboard folds around behind the screen; in such a system, a user 
could accidentally hit keys while using the stylus. This function is also new to Win- 
dows CE 2.0. | 

If you build an application to run under Windows CE 1.0, you'll need to explic- 
itly load both GetKeyboardStatus and EnableHardwareKeyboard using LoadLibrary 
and GetProcAddress to determine the address of these 2.0-specific functions. If a call 
is made directly to a 2.0 function from an application, that application is incompat- 
ible with Windows CE 1.0 and won’t load. 


The KeyTrac Example Program 


The following example program, KeyTrac, displays the sequence of keyboard mes- 
sages. Programmatically, KeyTrac isn’t much of a departure from the earlier programs 
in the book. The difference is that the keyboard messages I’ve been describing are 
all trapped and recorded in an array that’s then displayed during the WM_PAINT 
message. For each keyboard message, the message name is recorded along with the 
wParam and [Param values and a set of flags indicating the state of the shift keys. 
The key messages are recorded in an array because these messages can occur faster 
than the redraw can occur. Figure 3-4 shows the KeyTrac window after a few keys 
have been pressed. 
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“WM_KEYUP wP:O0000044 IP:coodoo 


W_CHAR WP 00000061 IP:O0000001 
WM_KEYDOWN wP 00000041 IP:00000001 
Wh _REYUP WP O0000041 IPicQO00001 
WM _KEYUP WP 00000010 IPicOO000001 
WM _CHAR WP 00000041 IP:00000001 


WhM_EREYDOWN WP 00000041 IP:OQ000001 shift ib 
WM_EEYDOWH WP:00000010 IP:O0000001 shift [5 


Figure 3-4. 7he KeyTrac window after a Shift-A key combination followed by a 
lowercase a key press. 


The best way to learn about the sequence of the keyboard messages is to run 
KeyTrac, press a few keys, and watch the messages scroll down the screen. Pressing 
a character key such as the a results in three messages: WM_KEYDOWN, WM_CHAR, 
and WM_KEYUP. Holding down the Shift key while pressing the a and then releas- 
ing the Shift key produces a key-down message for the Shift key followed by the three 
messages for the a key followed by a key-up message for the Shift key. Because the 
Shift key itself isn’t a character key, no WM_CHAR message is sent in response to it. 
However, the WM_CHAR message for the a key now contains a 0x41 in the wParam 
value, indicating that an uppercase A was entered instead of a lowercase a. 

Figure 3-5 shows the source code for the KeyTrac program. 


Figure 3-5. The KeyTrac program. 
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(continued) 
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Figure 3-5. continued 
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(continued) 
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(continued) 
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Figure 3-5. continued 
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which scrolls an area of the device context either horizontally or vertically, but under 
Windows CE, not both directions at the same time. The three rectangle parameters 
define the area to be scrolled, the area within the scrolling area to be clipped, and 
the area to be painted after the scrolling ends. Alternatively, a handle to a region can 
be passed to ScrollIDC. That region is defined by Scrol/DC to encompass the region 
that needs painting after the scroll. 

Finally, if the KeyTrac window is covered up for any reason and then re- 
exposed, the message information on the display is lost. This is because a device 
context doesn’t store the bit information of the display. The application is respon- 
sible for saving any information necessary to completely restore the client area of 
the screen. Since Keytrac doesn’t save this information, it’s lost when the window 
is covered up. 


THE STYLUS AND THE TOUCH SCREEN 


The stylus/touch screen combination is new to Windows platforms, but fortunately, 
its integration into Windows CE applications is relatively painless. The best way to 
deal with the stylus is to treat it as a single-button mouse. The stylus creates the same 
mouse messages that are provided by the mouse in other versions of Windows and 
by Windows CE systems that use a mouse. The differences that do appear between a 
mouse and a stylus are due to the different physical realities of the two input devices. 

Unlike a mouse, a stylus doesn’t have a cursor to indicate the current position 
of the mouse. Therefore a stylus can’t hover over a point on the screen in the way 
that the mouse cursor does. A cursor hovers when a user moves it over a window 
without pressing a mouse button. This concept can’t be applied to programming for 
a stylus because the touch screen can’t detect the position of the stylus when it isn’t 
in contact with the screen. 

Another consequence of the difference between a stylus and a mouse is that 
without a mouse cursor, an application can’t provide feedback to the user by means 
of changes in appearance of a hovering cursor. Windows CE does support setting 
the cursor for one classic Windows method of user feedback. The busy hourglass 
cursor, indicating that the user must wait for the system to complete processing, is 
supported under Windows CE so that applications can display the busy hourglass in 
the same manner as applications running under other versions of Windows, using 
the SetCursor function. 


Stylus Messages 


When the user presses the stylus on the screen, the topmost window under that 
point receives the input focus if it didn’t have it before and then receives a 
WM_LBUTTONDOWN message. When the user lifts the stylus, the window receives 
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a WM_LBUTTONUP message. Moving the stylus within the same window while it’s 
down causes WM_MOUSEMOVE messages to be sent to the window. For all of these — 
messages, the wParam and lParam parameters are loaded with the same values. The 
wParam parameter contains a set of bit flags indicating whether the Ctrl or Shift keys 
on the keyboard are currently held down. As in other versions of Windows, the Alt 
key state isn’t provided in these messages. To get the state of the Alt key when the 
message was sent, use the GetKeyState function. 

The /Param parameter contains two 16-bit values that indicate the position on 
the screen of the tap. The low-order 16 bits contains the x (horizontal) location rela- 
tive to the upper left corner of the client area of the window while the high-order 16 
bits contains the y (vertical) position. 

If the user double-taps, that is, taps twice on the screen at the same location 
and within a predefined time, Windows sends a WM_LBUTTONDBLCLK message to 
the double-tapped window, but only if that window’s class was registered with the 
CS_DBLCLKS style. The class style is set when the window class is registered with 
RegisterClass. | 

You can differentiate between a tap and a double-tap by comparing the mes- 
sages sent to the window. When a double-tap occurs, a window first receives the 
WM_LBUTTONDOWN and WM_LBUTTONUP messages from the original tap. Then 
a WM_LBUTTONDBLCLK is sent followed by another WM_LBUTTONUP. The trick 
is to refrain from acting on a WM_LBUTTONDOWN message in any way that pre- 
cludes action on a subsequent WM_LBUTTONDBLCLK. This is usually not a prob- 
lem because taps usually select an object while double-tapping launches the default 
action for the object. 


Inking 

A typical application for a handheld device is capturing the user’s writing on the screen 
and storing the result as ink. This isn’t handwriting recognition—simply ink storage. 
At first pass, the best way to accomplish this would be to store the stylus points passed 
in each WM_MOUSEMOVE message. The problem is that sometimes small CE-type 
devices can’t send these messages fast enough to achieve a satisfactory resolution. 
Under Windows CE 2.0, a new function call has been added to assist programmers in 
tracking the stylus. 


BOOL GetMouseMovePoints (PPOINT pptBuf, UINT nBufPoints, 
UINT *pnPointsRetrieved) ; 


GetMouseMovePoints returns a number of stylus points that didn’t result in 
WM_MOUSEMOVE messages. The function is passed an array of points, the size of 
the array (in points), and a pointer to an integer that will receive the number of points 
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passed back to the application. Once received, these additional points can be used 
to fill in the blanks between the last WM_MOUSEMOVE message and the current one. 

GetMouseMovePoints does throw one curve at you. It returns points in the reso- 
lution of the touch panel, not the screen. This is generally set at four times the screen 
resolution, so you need to divide the coordinates returned by GetMouseMovePoints 
by four to convert them to screen coordinates. The extra resolution helps programs 
such as handwriting recognizers. 

A short example program, PenTrac, illustrates the difference that GetMouseMove- 
Points can make. Figure 3-6 shows the PenTrac window. Notice the two lines of dots 
across the window. The top line was drawn using points from WM_MOUSEMOVE 
only. The second line included points that were queried with GetMouseMovePoints. 
The black dots were queried from WM_MOUSEMOVE while the red Cighter) dots 
were locations queried with GetMouseMovePoints. 


10:50 aM | 


Figure 3-6. Zhe PenTrac window showing two lines drawn. 


The source code for PenTrac is shown in Figure 3-7. The program places a dot 
on the screen for each WM_MOUSEMOVE or WM_LBUTTONDOWN message it re- 
ceives. If the Shift key is held down during the mouse move messages, PenTrac also 
calls GetMouseMovePoints and marks those points in the window in red to distinguish 
them from the points returned by the mouse messages alone. 

PenTrac cheats a little to enhance the effect of GetMouseMovePoints. In the 
DoMouseMain routine called to handle WM_MOUSEMOVE and WM_LBUTTON- 
DOWN messages, the routine calls the function sleep to kill a few milliseconds. This 
simulates a slow-responding application that might not have time to process every 
mouse move message in a timely manner. 
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The PenTrac program. 
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Input focus and mouse messages 
Here are some subtleties to note about circumstances that rule how and when mouse 
messages initiated by stylus input are sent to different windows. As I mentioned pre- 
viously, the input focus of the system changes when the stylus is pressed against a 
window. However, dragging the stylus from one window to the next won’t cause the 
new window to receive the input focus. The down tap sets the focus, not the process 
of dragging the stylus across a window. When the stylus is dragged outside the win- 
dow, that window stops receiving WM_MOUSEMOVE messages but retains input 
focus. Because the tip of the stylus is still down, no other window will receive the 
WM_MOUSEMOVE messages. This is akin to using a mouse and dragging the mouse 
outside a window with a button held down. 

To continue to receive mouse messages even if the stylus moves off its win- 
dow, an application can call 


HWND SetCapture (HWND hWnd); 


passing the handle of the window to receive the mouse messages. The function re- 
turns the handle of the window that previously had captured the mouse or NULL if 
the mouse wasn’t previously captured. To stop receiving the mouse messages initi- 
ated by stylus input, the window calls 


BOOL ReleaseCapture (void); 


Only one window can capture the stylus input at any one time. To determine 
whether the stylus has been captured, an application can call 


HWND GetCapture (void); 


which returns the handle of the window that has captured the stylus input or 0 if no 
window has captured the stylus input—although please note one caveat. The window 
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that has captured the stylus must be in the same thread context as the window calling 
the function. This means that if the stylus has been captured by a window in another 
application, GetCapture still returns 0. | 

If a window has captured the stylus input and another window calls GetCapture, 
the window that had originally captured the stylus receives a WM_CAPTURECHANGED 
message. The /Param parameter of the message contains the handle of the window 
that has gained the capture. You shouldn’t attempt to take back the capture by call- 
ing GetCapture in response to this message. In general, since the stylus is a shared 
resource, applications should be wary of capturing the stylus for any length of time 


_ and they should be able to handle gracefully any loss of capture. 


Another interesting tidbit: Just because a window has captured the mouse, that 
doesn’t prevent a tap on another window gaining the input focus for that window. 
You can use other methods for preventing the change of input focus, but in almost 
all cases, it’s better to let the user, not the applications, decide what top-level win- 
dow should have the input focus. 


Right-button clicks 

When you click the right mouse button on an object in Windows systems, the action 
typically calls up a context menu, which is a stand-alone menu displaying a set of 
choices for what you can do with that particular object. On a system with a mouse, 
Windows sends WM_RBUTTONDOWN and WM_RBUTTONUP messages indicating 
a right-button click. When you use a stylus however, you don’t have a right button. 
The Windows CE guidelines, however, allow you to simulate a right button click using 
a stylus. The guidelines specify that if a user holds down the Alt key while tapping 
the screen with the stylus, a program should act as if a right mouse button were be- 
ing clicked and display any appropriate context menu. Because there’s no MK_ALT 
flag in the wParam value of WM_LBUTTONDOWN, the best way to determine whether 
the Alt key is pressed is to use GetKeyState with VK_MENU as the parameter and test 
for the most significant bit of the return value to be set. GetKeyState is more appro- 
priate in this case because the value returned will be the state of the key at the time 
the mouse message was pulled from the message queue. 


The TicTac1 Example Program 


To demonstrate stylus programming, I have written a trivial tic-tac-toe game. The 
TicTacl window is shown in Figure 3-8. The source code for the program is shown 
in Figure 3-9. This program doesn’t allow you to play the game against the computer, 
nor does it determine the end of the game—it simply draws the board and keeps track 
of the Xs and Os. Nevertheless, it demonstrates basic stylus interaction. 
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HTicTacl 


Ce VAT EOP YT YY YYY EN OVO O VY VAY YOYV SOOTY 


Figure 3-9. The TicTacl program. (continued) 
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The action in TicTacl is centered around three routines: DrawBoard, DrawXO, 
and OnLButtonUpMain. The first two perform the tasks of drawing the playing board. 
The routine that determines the location of a tap on the board (and therefore is more 
relevant to our current train of thought) is OnLButtonUpMain. As the name suggests, 
this routine is called in response to a WM_LBUTTONUP message. The first action to 
take is to call 


BOOL PtInRect (const RECT *1prc, POINT pt); 


which determines whether the tap is even on the game board. The program knows 
the location of the tap because it’s passed in the /Param value of the message. The 
board rectangle is computed when the program starts in OnSizeMain. Once the tap 
is localized to the board, the program determines the location of the relevant cell within 
the playing board by dividing the coordinates of the tap point within the board by 
the number of cells across and down. 

I mentioned that the board rectangle was computed during the OnSizeMain 
routine, which is called in response to a WM_SIZE message. While it might seem 
strange that Windows CE supports the WM_SIZE message common to other versions 
of Windows, it needs to support this message because a window is sized frequently: 
first right after it’s created, and then each time it’s minimized and restored. You might 
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think that another possibility for determining the size of the window would be dur- 
ing the WM_CREATE message. The /Param parameter points to a CREATESTRUCT 
structure that contains, among other things, the initial size and position of the win- 
dow. The problem with using those numbers is that the size obtained is the total size 
of the window, not the size of client area, which is what we need. Under Windows 
CE, most windows have no title bar and no border, but some have both and many 
have scroll bars, so using these values can cause trouble. So now, with the TicTacl 
example, we have a simple program that uses the stylus effectively but isn’t complete. 
To restart the game, we must exit and restart TicTacl. We can’t take back a move nor 
have O start first. We need a method for sending these commands to the program. 
Sure, using keys would work. Another solution would be to create hot spots on the 
screen that when tapped, provided the input necessary. However, the standard method 
of exercising these types of commands in a program is through menus. 


MENUS 


Menus are a mainstay of Windows input. While each application might have a differ- 
ent keyboard and stylus interface, almost all have sets of menus that are organized in 
a structure familiar to the Windows user. 

Windows CE programs use menus a little differently from other Windows pro- 
grams, the most obvious difference being that in Windows CE, menus aren’t part of 
the standard window. Instead, menus are attached to the command bar control that 
has been created for the window. Other than this change, the functions of the menu 
and the way menu selections are processed by the application match the other ver- 
sions of Windows, for the most part. Because of this general similarity, I give you 
only a basic introduction to Windows menu management in this section. 

Creating a menu is as simple as calling 


HMENU CreateMenu (void): 


The function returns a handle to an empty menu. To add an item to a menu, two 
calls can be used. The first, 


BOOL AppendMenu (HMENU hMenu, UINT fuFlags, UINT idNewItem, 
LPCTSTR IpszNewItem) ; 


appends a single item to the end of a menu. The /uFlags parameter is set with a series 
of flags indicating the initial condition of the item. For example, the item might be 
initially disabled (thanks to the MF_GRAYED flag) or have a check mark next to it (cour- 
tesy of the MF_CHECKED flag). Almost all calls specify the MF_STRING flag, indicat- 
ing that the /pszNewltem parameter contains a string that will be the text for the item. 
The idNewliem parameter contains an ID value that will be used to identify the item 
when it’s selected by the user or that the state of the menu item needs to be changed. 
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Another call that can be used to add a menu item is this one: 


BOOL InsertMenu (HMENU hMenu, UINT uPosition, UINT uFlags, 
UINT uIlDNewItem, LPCTSTR 1lpNewI!tem); 


This call is similar to AppendMenu with the added flexibility that the item can be in- 
serted anywhere within a menu structure. For this call, the uwFlags parameter can be 
passed one of two additional flags: MF_BYCOMMAND or MF_BYPOSITION, which 
specify how to locate where the menu item is to be inserted into the menu. 

Under Windows CE 2.0, menus can be nested to provide a cascading effect. This 
feature brings Windows CE up to the level of other versions of Windows, which have 
always allowed cascading menus. To add a cascading menu, or submenu, create the 
menu you want to attach using CreateMenu and InsertMenu. Then insert or append 
the submenu to the main menu using either InsertMenu or AppendMenu with the 
MF_POPUP flag in the flags parameter. In this case, the uJDNewltem parameter con- 
tains the handle to the submenu while the JpNewltem contains the string that will be 
on the menu item. 

You can query and manipulate a menu item to add or remove check marks or 
to enable or disable it by means of a number of functions. This function, 


BOOL EnableMenuItem (HMENU hMenu, UINT uIDEnableItem, UINT uEnable); 


can be used to enable or disable an item. The flags used in the uEnable parameter 
are similar to the flags used with other menu functions. Under Windows CE, the flag 
you use to disable a menu item is MF_GRAYED, not MF_DISABLED. The function 


DWORD CheckMenuItem (HMENU hmenu, UINT ulIDCheckIitem, UINT uCheck); 


can be used to check and uncheck a menu item. Many other functions are available 
to query and manipulate menu items. Check the SDK documentation for more details. 
The following code fragment creates a simple menu structure: 


hMainMenu = CreatePopupMenu (); 


hMenu = CreateMenu (); 

AppendMenu (hMenu, MF_STRING | MF_ENABLED, 100, TEXT ("&New")); 
AppendMenu (hMenu, MF_STRING | MF_ENABLED, 101, TEXT ("&Open")); 
AppendMenu (hMenu, MF_STRING | MF_ENABLED, 101, TEXT ("&Save")); 
AppendMenu (hMenu, MF_STRING | MF_ENABLED, 101, TEXT ("E&xit"™)); 


AppendMenu (hMainMenu, MF_STRING | MF_ENABLED | MF_POPUP, (UINT)hMenu, 
TEXT ("&File”)); 


hMenu = CreateMenu (); 

AppendMenu (hMenu, MF_STRING | MF_ENABLED, 100, TEXT ("C&ut"™)); 
AppendMenu (hMenu, MF_STRING | MF_ENABLED, 101, TEXT ("&Copy"™)); 
AppendMenu (hMenu, MF_STRING | MF_LENABLED, 101, TEXT ("&Paste")); 
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AppendMenu (hMainMenu, MF_STRING | MF_ENABLED | MF_POPUP, hMenu, 
TEXT ("&Edit")); 


hMenu = CreateMenu (); 
AppendMenu (hMenu, MF_STRING | MF_ENABLED, 100, TEXT ("&About"™)); 


AppendMenu (hMainMenu, MF_STRING | MF_ENABLED | MF_POPUP, hMenu, 
TEXT ("&Help™)); 


Once a menu has been created, it can be attached to a command bar using this 
function: 


BOOL CommandBar_InsertMenubarEx (HWND hwndCB, HINSTANCE hInst, 
LPTSTR pszMenu, int iButton); 


The menu handle is passed in the third parameter while the second parameter, inst, 
must be 0. The final parameter, iButton, indicates the button that will be to the im- 
mediate right of the menu. The Windows CE user interface guidelines recommend 
that the menu be on the far left of the command bar, so this value is almost always 0. 


Handling Menu Commands 


When a user selects a menu item, Windows sends a WM_COMMAND message to the 
window that owns the menu. The low word of the wParam parameter contains the 
ID of the menu item that was selected. The high word of wParam contains the noti- 
fication code. For a menu selection, this value is always 0. The /Param parameter is 
0 for WM_COMMAND messages sent due to a menu selection. Those familiar with 
Windows 3.x programming might notice that the layout of wParam and lParam match 
the standard Win32 assignments and are different from Win16 programs. So, to act 
on a menu selection, a window needs to field the WM_COMMAND message, decode 
the ID passed, and act according to the menu item that was selected. 

Now that I’ve covered the basics of menu creation, you might wonder where 
all this menu creation code sits in a Windows program. The answer is, it doesn’t. Instead 
of dynamically creating menus on the fly, most Windows programs simply load a menu 
template from a resource. To learn more about this, let’s take a detour from the de- 
scription of input methods and look at resources. 


RESOURCES 


Resources are read-only data segments of an application or a DLL that are linked to 
the file after it has been compiled. The point of a resource is to give a developer a 
compiler-independent place for storing content data such as dialog boxes, strings, 
bitmaps, icons, and yes, menus. Since resources aren’t compiled into a program, they 
can be changed without having to recompile the application. 
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You create a resource by building an ASCII file—called a resource script— 
describing the resources. Your ASCII file has an extension of RC. You compile this 
file with a resource compiler, which is provided by every maker of Windows devel- 
opment tools, and then you link them into the compiled executable again using the 
linker. These days, these steps are masked by a heavy layer of visual tools, but the 
fundamentals remain the same. For example, Visual C++ 5.0 creates and maintains 
an ASCII resource (RC) file even though few programmers directly look at the resource 
file text any more. 

It’s always a struggle for the author of a programming book to decide how to 
approach tools. Some lay out a very high level of instruction, talking about menu 
selections and describing dialog boxes for specific programming tools. Others show 
the reader how to build all the components of a program from the ground up, using 
ASCII files and command line compilers. Resources can be approached the same way: 
I could describe how to use the visual tools or how to create the ASCII files that are 
the basis for the resources. In this book, I stay primarily at the ASCII resource script 
level since the goal is to teach Windows CE programming, not how to use a particu- 
lar set of tools. Pll show how to create and use the ASCII RC file for adding menus 
and the like, but later in the book in places where the resource file isn’t relevant, I 
won't always include the RC file in the listings. The files are, of course, on the CD 
included with this book. 


Resource Scripts 
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Creating a resource script is as simple as using Notepad to create a text file. The lan- 
guage used is simple, with C-like tendencies. Comment lines are prefixed by a double 
slash (//) and files can be included using a #include statement. 

An example menu template would be the following: 


// 
// A menu template 
// 
ID_MENU MENU DISCARDABLE 
BEGIN 
POPUP "&File™ 
BEGIN 
MENUITEM “&Open...", 100 
MENUITEM "&Save...", 101 
MENUITEM SEPARATOR 
MENUITEM “E&xit", 120 
END 
POPUP "&Help” 
BEGIN 
MENUITEM "&About", 200 
END 
END 
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The initial ID_MENU is the ID value for the resource. Alternatively, this ID value 
can be replaced by a string identifying the resource. The ID value method provides 
more compact code while using a string may provide more readable code when 
the application loads the resource in the source file. The next word, MENU, identi- 
fies the type of resource. The menu starts with POPUP, indicating that the menu item 
File is actually a pop-up (cascade) menu attached to the main menu. Because it’s a 
menu within a menu, it too has BEGIN and END keywords surrounding the descrip- 
tion of the File menu. The ampersand (&) character tells Windows that the next char- 
acter should be the key assignment for that menu item. The character following the 
ampersand is automatically underlined by Windows when the menu item is displayed, 
and if the user presses the Alt key along with the character, that menu item is selected. 
Each item in a menu is then specified by the MENUITEM keyword followed by the 
string used on the menu. The ellipsis following the Open and Save strings is a Win- 
dows UI custom indicating to the user that selecting that item displays a dialog box. 
The numbers following the Open, Save, Exit, and About menu items are the menu 
identifiers. These values identify the menu items in the WM_COMMAND message. 
It’s good programming practice to replace these values with equates that are defined 
in a common include file so that they match the WM_COMMAND handler code. 

Figure 3-10 lists other resource types that you might find in a resource file. The 
DISCARDABLE keyword is optional and tells Windows that the resource can be dis- 
carded from memory if it’s not in use. The remainder of the menu is couched in BEGIN 
and END keywords, although bracket characters { and } are recognized as well. 


Resource Type Explanation 

MENU Defines a menu 

ACCELERATORS Defines a keyboard accelerator table 
DIALOG Defines a dialog box template 

BITMAP Includes a bitmap file as a resource 

ICON Includes an icon file as a resource 

FONT Includes a font file as a resource 

RCDATA Defines application-defined binary data block 
STRINGTABLE Defines a list of strings 

VERSIONINFO Includes file version information 


Figure 3-10. 7he resource types allowed by the resource compiler. 
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Now that we’re working with resource files, it’s a trivial matter to: modify the icon 
that the Windows CE shell uses to display a program. Simply create an icon with your 
favorite icon editor and add to the resource file an icon statement such as 


ID_ICON ICON "tictac2.ico" 


When Windows displays a program in Windows Explorer, it looks inside the EXE file 
for the first icon in the resource list and uses it to represent the program. 

Having that icon represent an application’s window is somewhat more of a chore. 
Windows CE uses a small 16-by-16-pixel icon on the taskbar to represent windows 
on the desktop. Under other versions of Windows, the RegisterClassEx function could 
be used to associate a small icon with a window, but Windows CE doesn’t support 
this function. Instead, the icon must be explicitly loaded and assigned to the win- 
dow. The following code fragment assigns a small icon to a window. 


hIcon = (HICON) SendMessage (hWnd, WM_GETICON, FALSE, @Q); 
if (hIcon == @) { 
hIcon = LoadImage (hInst, MAKEINTRESOURCE (ID_ICON1), IMAGE_ICON, 
16, 16, Q@); 
SendMessage (hWnd, WM_SETICON, FALSE, (LPARAM)hIcon); 
} 


The first SendMessage call gets the currently assigned icon for the window. The 
FALSE value in wParam indicates that we’re querying the small icon for the window. 
If this returns 0, indicating that no icon has been assigned, a call to LoadImage is made 
to load the icon from the application resources. The LoadImage function can take 
either a text string or an ID value to identify the resource being loaded. In this case, 
the MAKEINTRESOURCE macro is used to label an ID value to the function. The icon 
being loaded must be a 16-by-16 icon because under Windows CE, LoadIlmage won't 
resize the icon to fit the requested size. Also under Windows CE, LoadImage is lim- 
ited to loading icons and bitmaps from resources. Windows CE provides the function 
ShLoadDIBitmap to load a bitmap from a file. 

Unlike other versions of Windows, Windows CE stores window icons on a per 
class basis. This means if two windows in an application have the same class, they 
share the same window icon. A subtle caveat here—window classes are specific to a 
particular instance of an application. So, if you have two different instances of the 
application FOOBAR, they each have different window classes, so they may have 
different window icons even though they were registered with the same class infor- 
mation. If the second instance of FOOBAR had two windows of the same class open, 
those two windows would share the same icon, independent of the window icon in 
the first instance of FOOBAR. 
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Accelerators 


Another resource that can be loaded is a keyboard accelerator table. This table is used 
by Windows to enable developers to designate shortcut keys for specific menus or 
controls in your application. Specifically, accelerators provide a direct method for a 
key combination to result in a WM_COMMAND message being sent to a window. 
These accelerators are different from the Alt-F key combination that, for example, 
can be used to access a File menu. File menu key combinations are handled auto- 
matically as long as the File menu item string was defined with the & character, as in 
GFile. The keyboard accelerators are independent of menus or any other controls, 
although their assignments typically mimic menu operations, as in using Ctrl-O to 
open a file. 
Below is a short resource script that defines a couple of accelerator keys. 


ID_ACCEL ACCELERATORS DISCARDABLE 
BEGIN 
"N", IDM_NEWGAME, VIRTKEY, CONTROL 
"Z", IDM_UNDO, VIRTKEY, CONTROL 
END 


As with the menu resource, the structure starts with an ID value. The ID value 
is followed by the type of resource and, again optionally, the discardable keyword. 
The entries in the table consist of the letter identifying the key, followed by the ID 
value of the command, VIRTKEY, which indicates that the letter is actually a virtual 
key value, followed finally by the CONTROL keyword, indicating that the control shift 
must be pressed with the key. 

Simply having the accelerator table in the resource doesn’t accomplish much. 
The application must load the accelerator table and, for each message it pulls from 
the message queue, see whether an accelerator has been entered. Fortunately, this is 
accomplished with a few simple modifications to the main message loop of a pro- 
gram. Here’s a modified main message loop that handles keyboard accelerators. 


// Load accelerator table. 
hAccel = LoadAccelerators (hInst, MAKEINTRESOURCE (ID_ACCEL)); 


// Application message loop 
while (GetMessage (&msg, NULL, 0, 0)) { 
// Translate accelerators 
if (!TranslateAccelerator (hwndMain, hAccel, &msg)) { 
TranslateMessage (&msg); 
DispatchMessage (&msg); 
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The first difference in this main message loop is the loading of the accelerator 
table using the LoadAccelerators function. Then after each message is pulled from 
the message queue, a call is made to TranslateAccelerator. If this function trans- 
lates the message, it returns TRUE, which skips the standard TranslateMessage and 
DispatchMessage loop body. If no translation was performed, the loop body ex- 
ecutes normally. 


Bitmaps 


Bitmaps can also be stored as resources. Windows CE works with bitmap resources 
somewhat differently from other versions of Windows. With Windows CE, the call 


HBITMAP LoadBitmap(HINSTANCE hInstance, LPCTSTR 1lpBitmapName) ; 


loads a read-only version of the bitmap. This means that after the bitmap is selected 
into a device context, the image can’t be modified by other drawing actions in that 
DC. To load a read/write version of a bitmap resource, use the LoadImage function. 


Strings 
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String resources are a good method for reducing the memory footprint of an appli- 
cation while keeping language-specific information out of the code to be compiled. 
An application can call 


int LoadString(HINSTANCE hInstance, UINT uID, LPTSTR IlpBuffer, 
int nBufferMax); 


to load a string from a resource. The ID of the string resource is uJD, the pBuffer 
parameter points to a buffer to receive the string, and nBufferMax is the size of the 
buffer. To conserve memory, LoadString has a new feature under Windows CE. If 
IpBuffer is NULL, LoadString returns a read-only pointer to the string as the return 
value. Simply cast the return value as a pointer to a constant Unicode string WPCTSTR) 
and use the string as needed. The length of the string, not including any null termi- 
nator, will be located in the word immediately preceding the start of the string. 

While I will be covering memory management and strategies for memory con- 
servation in Chapter 6, one quick note here. It’s not a good idea to load a number of 
strings from a resource into memory. This just uses memory both in the resource and 
in RAM. If you need a number of strings at the same time, it might be a better strategy 
to use the new feature of LoadString to return a pointer directly to the resource itself. 
As an alternative, you can have the strings in a read-only segment compiled with the 
program. You lose the advantage of a separate string table, but you reduce your 
memory footprint. 
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The TicTac2 Example Program 


The final program in this chapter encompasses all of the information presented up to 
this point as well as a few new items. The TicTac2 program is an extension of TicTac1; 
the additions are a menu, a window icon, and keyboard accelerators. The TicTac2 


window, complete with menu, is shown in Figure 3-11, while the source is shown in 
Figure 3-12. 


's turn 


5 5:03 PM 


Figure 3-11. 7he TicTac2 window winsertDelete (Many Windows CE keyboards use 
Shift-Backspace for this function.) 


Figure 3-12. Zhe Tictac2 program. (continued) 
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(continued) 
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Figure 3-12. continued 
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The biggest change in TicTac2 is the addition of a WM_COMMAND handler in 
the form of the routine OnCommandMain. Because a program might end up han- 
dling a large number of different menu items and other controls, I extend the table- 
lookup design of the window procedure to another table lookup for command IDs 
from menus and accelerators. For TicTac2, I use three command handlers, one for 
each of the menu items. This results in another table of IDs and procedure pointers 
that associates menu IDs with handler procedures. Again, this way of using a table 
lookup instead of the standard switch statement isn’t necessary or specific to Win- 
dows CE. It’s simply my programming style. 

The first menu handler, OnCommandNewGame, simply calls the reset game 
routine to clear the game structures. The routine itself returns 0, which is the default 
value for a WM_COMMAND handler. 

The OnCommandUndo command handler is interesting in that it isn’t always 
enabled. TicTac2 handles an additional message WM_INITMENUPOPUP, which is sent 
to a window immediately before the window menu is displayed. This gives the win- 
dow a chance to initialize any of the menu items. In this case, the routine 
OnInitMenuPopMain looks to see whether the bLastMove field contains a valid cell 
value (O through 8). If not, the routine disables the Undo menu item using 
EnableMenultem. This action also disables the keyboard accelerator for that menu 
item as well. 

The final command handler, OnCommandExit, sends a WM_CLOSE message 
to the main window. Closing the window eventually results in Windows sending a 
WM_DESTROY message, which results in a PostQuitMessage call that terminates the 
program. Sending a WM_CLOSE message is, by the way, the same action that results 
from clicking on the Close button on the command bar. 

Other changes from the first TicTac example include modification of the mes- 
sage loop to provide for keyboard accelerators and the addition of code in the 
OnCreateMain routine to load and assign a window icon. Also, the string prompts 
for whose turn it is are loaded from the resource file. 

Looking at the OnCommandNewGame handler introduces one last new func- 
tion. If the game isn’t complete, the program asks the players whether they really want 
to clear the game board. This query is accomplished by calling 


int MessageBox (HWND hWnd, LPCTSTR IpText, LPCTSTR IpCaption, 
UINT uType); 
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This function displays a message box, a simple dialog box, with definable text and 
buttons. A message box can display a message along with a limited series of buttons. 
Message boxes are often used to query users for a simple response or to notify them 
of some event. The u7ype parameter allows the programmer to select different but- 
ton configurations, such as Yes/No, OK/Cancel, Yes/No/Cancel, and simply OK. You 
can also select an icon to appear in the message box that signals the level of impor- 
tance of the answer. 

A message box is essentially a poor man’s dialog box. It offers a simple method 
of querying the user but little flexibility in how the dialog box is configured. Now 
that we’ve introduced the subject of dialog boxes, it’s time to take a closer look at 
them and other types of secondary and child windows. 


Chapter 4 


Windows, Controls, 
and Dialog Boxes 


Understanding how windows work and relate to each other is the key to understanding 
the user interface of the Microsoft Windows operating system, whether it be Microsoft 
Windows 98, Microsoft Windows NT, or Microsoft Windows CE. Everything you see 
on a Windows display is a window. The desktop is a window, the taskbar is a win- 
dow, even the Start button on the taskbar is a window. Windows are related to one 
another according to one relationship model or another; they may be in parent/child, 
sibling, or owner/owned relationships. Windows supports a number of predefined 
window classes, called controls. These controls simplify the work of programmers 
by providing a range of predefined user interface elements as simple as a button or 
as complex as a multiline text editor. Windows CE supports the same standard set of 
built-in controls as the other versions of Windows. These built-in controls shouldn’t 
be confused with the complex controls provided by the common control library. I'll 
talk about those controls in Chapter 5. 

Controls are usually contained in dialog boxes (sometimes simply referred to 
as dialogs). These dialog boxes constitute a method for a program to query users for 
information the program needs. A specialized form of dialog, named a property sheet, 
allows a program to display multiple but related dialog boxes in an overlapping style; 
each box or property sheet is equipped with an identifying tab. Property sheets are 
particularly valuable given the tiny screens associated with Windows CE devices. 
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Finally, Windows CE supports a subset of the common dialog library available 
under Windows NT and Windows 98. Specifically, Windows CE supports versions of 
the common dialog boxes File Open, File Save, Color, and Print. These dialogs are 
somewhat different on Windows CE. They’re reformatted for the smaller screens and 
aren’t as extensible as their desktop counterparts. 


CHILD WINDOWS 
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Each window is connected via a parent/child relationship scheme. Applications cre- 
ate a main window with no parent, called a top-level window. That window might 
(or might not) contain windows, called child windows. A child window is clipped to 
its parent. That is, no part of a child window is visible beyond the edge of its parent. 
Child windows are automatically destroyed when their parent windows are destroyed. 
Also, when a parent window moves, its child windows move with it. 

Child windows are programmatically identical to top-level windows. You use 
the CreateWindow or CreateWindowEx function to create them, each has a window 
procedure that handles the same messages as its top-level window, and each can, in 
turn, contain its own child windows. To create a child window, use the WS_CHILD 
window style in the dwStyle parameter of CreateWindow or CreateWindowEx. In 
addition, the bMenu parameter, unused in top-level Windows CE windows, passes 
an ID value that you can use to reference the window. 

Under Windows CE, there’s one other major difference between top-level win- 
dows and child windows. Windows sends WM_HIBERNATE messages only to top- 
level windows that have the WS_OVERLAPPED and WS_VISIBLE styles. (Window 
visibility in this case has nothing to do with what a user sees. A window can be “vis- 
ible” to the system and still not be seen by the user if other windows are above it in 
the Z-order.) This means that child windows and most dialog boxes aren’t sent 
WM_HIBERNATE messages. Top-level windows must either manually send a 
WM_HIBERNATE message to their child windows as necessary or perform all the 
necessary tasks themselves to reduce the application’s memory footprint. On Win- 
dows CE systems, such as the H/PC that support application buttons on the taskbar, 
the rules for determining the target of WM_HIBERNATE messages are also used to 
determine what windows get buttons on the taskbar. 

In addition to the parent/child relationship, windows also have an owner/owned 
relationship. Owned windows aren’t clipped to their owners. However, they always 
appear “above” Gin Z-order) the window that owns them. If the owner window is 
minimized, all windows it owns are hidden. Likewise, if a window is destroyed, all 
windows it owns are destroyed. Windows CE 1.0 supports window ownership only 
for dialog boxes, but from version 2.0 on, Windows CE provides full support for owned 
windows. 
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Window Management Functions 


Given the windows-centric nature of Windows, it’s not surprising that you can choose 
from a number of functions that enable a window to interrogate its environment so 
that it might determine its location in the window family tree. To find its parent, a 
window can call 


HWND GetParent (HWND hWnd); 


This function is passed a window handle and returns the handle of the calling window’s 
parent window. If the window has no parent, the function returns NULL. 


Enumerating windows 
GetWindow, prototyped as 


HWND GetWindow (HWND hWnd, UINT uCmd); 


is an omnibus function that allows a window to query its children, owner, and sib- 
lings. The first parameter is the window’s handle while the second is a constant that 
indicates the requested relationship. The GW_CHILD constant returns a handle to the 
first child window of a window. GetWindow returns windows in Z-order, so the first 
window in this case is the child window highest in the Z-order. If the window has no 
child windows, this function returns NULL. The two constants, GW_HWNDFIRST and 
GW_HWNDLAST, return the first and last windows in the Z-order. If the window handle 
passed is a top-level window, these constants return the first and last topmost win- 
dows in the Z-order. If the window passed is a child window, the GetWindow function 
returns the first and last sibling window. The GW_HWNDNEXT and GW_HWNDPREV 
constants return the next lower and next higher windows in the Z-order. These con- 
stants allow a window to iterate through all the sibling windows by getting the next 
window, then using that window handle with another call to GetWindow to get the 
next, and so on. Finally, the GW_OWNER constant returns the handle of the owner 
of a window. 
Another way to iterate through a series of windows is 


BOOL EnumWindows (WNDENUMPROC 1IpEnumFunc, LPARAM 1Param); 


This function calls the callback function pointed to by jpEnumFunc once for each 
top-level window on the desktop, passing the the handle of each window in turn. 
The /Param value is an application-defined value, which is also passed to the enu- 
meration function. This function is better than iterating through a GetWindow loop 
to find the top-level windows because it always returns valid window handles; it’s 
possible that a GetWindow iteration loop will get a window handle whose window 
is destroyed before the next call to GetWindow can occur. However, since 
EnumWindows works only with top-level windows, GetWindow still has a place when 
iterating through a series of child windows. \ 
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Finding a window 
To get the handle of a specific window, use the function 


at Le 


HWND FindWindow (LPCTSTR IpClassNam LPCTSTR loWindowName) ; 


This function can find a window either by means of its window class name or by means 
of a window’s title text. This function is handy when an application is just starting 
up; it can determine whether another copy of the application is already running. All 
an application has to do is call FindWindow with the name of the window class for 
the main window of the application. Because an application almost always has a main 
window while it’s running, a NULL returned by FindWindow indicates that the func- 
tion can’t locate another window with the specified window class—therefore, it’s 
almost certain that another copy of the application isn’t running. 


Editing the window structure values 
The pair of functions 


LONG GetWindowLong (HWND hWnd, int nIndex); 
and 
LONG SetWindowLong (HWND hWnd, int nIndex, LONG dwNewLong); 


allow an application to edit data in the window structure for a window. Remember 
the WNDCLASS structure passed to the RegisterClass function has a field, chWndExtra, 
that controls the number of extra bytes that are to be allocated after the structure. If 
you allocated extra space in the window structure when the window class was reg- 
istered, you can access those bytes using the GetWindowLong and SetWindowLong 
functions. Under Windows CE, the data must be allocated and referenced in 4-byte 
(integer sized and aligned) blocks. So, if a window class was registered with 12 in 
the cbWndExtra field, an application can access those bytes by calling GetWindowLong 
or SetWindowLong with the window handle and by setting values of 0, 4, and 8 in 
the nIndex parameter. 

GetWindowLong and SetWindowLong support a set of predefined index values 
that allow an application access to some of the basic parameters of a window. Here 
is a list of the supported values for Windows CE. 


MH GWI_STYIE The style flags for the window 
GWL_EXSTYLE The extended style flags for the window 
GWL_WNDPROC The pointer to the window procedure for the window 


Ki 

nt 

M GWI_ID ‘The ID value for the window 

M = GWI_USERDATA An application-usable 32-bit value 
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Dialog box windows support the following additional values: 


M DWI_DLGPROC The pointer to the dialog procedure for the window 


M DWI_MSGRESULT The value returned when the dialog box function 
returns 


M DWI_USER An application-usable 32-bit value 


Windows CE doesn’t support the GWL_HINSTANCE and GWL_HWNDPARENT 
values supported by Windows NT and Windows 98. 


Scroll Bars and the FontList2 Example Program 


To demonstrate a handy use for a child window, we return to the FontList program 
from Chapter 2. As you might remember, the problem was that if a scroll bar were 
attached to the main window of the application, the scroll bar would extend upward, 
past the right side of the command bar. The reason for this is that a scroll bar attached 
to a window is actually placed in the nonclient area of that window. Because the com- 
mand bar lies in the client space, we have no easy way to properly position the two 
controls in the same window. 

An easy way to solve this problem is to use a child window. We place the child 
window so that it fills all of the client area of the top-level window not covered by 
the command bar. The scroll bar can then be attached to the child window so that it 
appears on the right side of the window but stops just beneath the command bar. 
Figure 4-1 shows the Fontlist2 window. Notice that the scroll bar now fits properly 
underneath the command bar. Also notice that the child window is completely un- 
detectable by the user. 


Times New Roman Point:24 


Faruly: Symbol Number of fonts:2 
ZwGor Tow 12 


awuwos Tow: 14 


Farnily: Anal Number of fonts:6 
Arial Point:10 
Arial Point 
Arial Point:12 


Anal Point13 
Arial Point:18 


Figure 4-1. The FontList2 window with the scroll bar properly positioned just beneath 
the command bar. 
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Figure 4-2. The FontList2 program. 
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(continued) 
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Figure 4-2. continued 
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(continued) 
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(continued) 
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Figure 4-2. continued 
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The window procedure for the frame window is quite simple. Just as in the 
original FontList program in Chapter 2, the command bar is created in the 
WM_CREATE message handler, DoCreateFrame. Now, however, this procedure also 
calls CreateWindow to create the child window in the area underneath the command 
bar. The child window is created with three style flags: WS_VISIBLE, so that the win- 
dow is initially visible, WS_CHILD, required because it will be a child window of the 
frame window; and WS_VSCROLL to add the vertical scroll bar to the child window. 
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The majority of the work for the program is handled in the client window pro- 
cedure. Here the same font enumeration calls are made to query the fonts in the sys- 
tem. The WM_PAINT handler, DoPaintClient, has a new characteristic: it now bases 
what it paints on the new global variable sVPos, which provides vertical positioning. 
That variable is initialized to 0 in DoCreateClient and is changed in the handler for a 
new message, WM_VSCROLL. 


Scroll bar messages 

A WM_VSCROLL message is sent to the owner of a vertical scroll bar any time the user 
taps on the scroll bar to change its position. A complementary message, WM_HSCROLL, 
is identical to WM_VSCROLL but is sent when the user taps on a horizontal scroll bar. 
For both these messages, the wParam and lParam assignments are the same. The 
low word of the wParam parameter contains a code indicating why the message was 
sent. Figure 4-3 shows a diagram of horizontal and vertical scroll bars and how tap- 
ping on different parts of the scroll bars results in different messages. The high word 
of wParam is the position of the thumb, but this value is valid only while you’re pro- 
cessing the SB_THUMBPOSITION and SB_THUMBTRACK codes, which I'll explain 
shortly. If the scroll bar sending the message is a stand-alone control and not attached 
to a window, the /Param parameter contains the window handle of the scroll bar. 


SB_LINEUP 
SB_PAGEUP 
SB_THUMBPOSITION 
SB_THUMBTRACK 


SB_PAGEDOWN 
SB_LINEDOWN 


SB_LINELEFT SB_THUMBPOSITION SB_LINERIGHT 
SB_PAGELEFT SB_THUMBTRACK SB_PAGERIGHT 


Figure 4-3. Scroll bars and their hot spots. 


The scroll bar message codes sent by the scroll bar allow the program to react 
to all the different user actions allowable by a scroll bar. The response required by 
each code is listed in the following table, Figure 4-4. 

The SB_LINExxx and SB_PAGExxx codes are pretty straightforward. You move 
the scroll position either a line or a page at a time. The SB_THUMBPOSITION and 
SB_THUMBTRACK codes can be processed in one of two ways. When the user drags 
the scroll bar thumb, the scroll bar sends SB_THUMBTRACK code so that a program 
can interactively track the dragging of the thumb. If your application is fast enough, 
you can simply process the SB_THUMBTRACK code and interactively update the 
display. If you field the SB_THUMBTRACK code, however, your application must be 


Chapter 4 Windows, Controls, and Dialog Boxes 


quick enough to redraw the display so that the thumb can be dragged without hesi- 
tation or jumping of the scroll bar. This is especially a problem on the slower devices 
that run Windows CE. 


Codes Response 


For WS_VSCROLL 


SB_LINEUP Program should scroll the screen up one line. 

SB_LINEDOWN Program should scroll the screen down one line. 

SB_PAGEUP Program should scroll the screen up one screen’s 
worth of data. 

SB_PAGEDOWN Program should scroll the screen down one 


screen’s worth of data. 


For WS_HSCROLL 


SB_LINELEFT Program should scroll the screen left one character. 
SB_LINERIGHT Program should scroll the screen right one character. 
SB_PAGELEFT Program should scroll the screen left one screen’s 


worth of data. 


SB_PAGERIGHT Program should scroll the screen right one screen’s 
worth of data. 


For both WS_VSCROLL and WS_HSCROLL 


SB_THUMBTRACK Programs with enough speed to keep up should 
update the display with the new scroll position. 
SB_THUMBPOSITION Programs that can’t update the display fast enough 


to keep up with the SB_THUMBTRACK message 
should update the display with the new scroll 


position. 

SB_ENDSCROLL This code indicates that the scroll bar has com- 
pleted the scroll event. No action is required by the 
program. 

SB_TOP Program should set the display to the top or left end 
of the data. 

SB_BOTTOM Program should set the display to the bottom or 


right end of the data. 


Figure 4-4. Scroll codes. 
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If your application (or the system it’s running on) is too slow to quickly update 
the display for every SB_THUMBTRACK code, you can ignore the SB_THUMBTRACK 
and wait for the SB_THUMBPOSITION code that’s sent when the user drops the scroll 
bar thumb. Then you have to update the display only once, after the user has fin- 
ished moving the scroll bar thumb. 


Configuring a scroll bar 

To use a scroll bar, an application should first set the minimum and maximum val- 
ues—the range of the scroll bar, along with the initial position. Windows CE scroll 
bars, like their Win32 cousins, support proportional thumb sizes, which provide feed- 
back to the user about the size of the current visible page compared to the entire 
scroll range. To set all these parameters, Windows CE applications should use the 
SetScrollinfo function, prototyped as 


int SetScrolliInfo (HWND hwnd, int fnBar, LPSCROLLINFO lpsi, BOOL fRedraw); 


The first parameter is either the handle of the window that contains the scroll 
bar or the window handle of the scroll bar itself. The second parameter, /nBar, is a 
flag that determines the use of the window handle. The scroll bar flag can be one of 
three values: SB_HORZ for a window’s standard horizontal scroll bar, SB_VERT for a 
window’s standard vertical scroll bar, or SB_CTL if the scroll bar being set is a stand- 
alone control. Unless the scroll bar is a control, the window handle is the handle of 
the window containing the scroll bar. With SB_CTL, however, the handle is the win- 
dow handle of the scroll bar control itself. The last parameter is fRedraw, a Bool- 
ean value that indicates whether the scroll bar should be redrawn after the call has 
been completed. 

The third parameter is a pointer to a SCROLLINFO structure, which is defined as 


typedef struct tagSCROLLINFO { 
UINT cbSize; 
UINT fMask; 
int nMin; 
int nMax; 
UINT nPage; 
int nPos; 
int nTrackPos; 
} SCROLLINFO; 


This structure allows you to completely specify the scroll bar parameters. The cbSize 
field must be set to the size of the SCROLLINFO structure. The fMask field contains 
flags indicating what other fields in the structure contain valid data. The nMin and 
nMax fields can contain the minimum and maximum scroll values the scroll bar can 
report. Windows looks at the values in these fields if the fMask parameter contains 
the SIF_RANGE flag. Likewise, the Pos field sets the position of the scroll bar within 
its predefined range if the fMask field contains the SIF_POS flag. 
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The Page field allows a program to define the size of the currently viewable 
area of the screen in relation to the entire scrollable area. This allows a user to have 
a feel for how much of the entire scrolling range is currently visible. This field is used 
only if the (Mask field contains the SIF_PAGE flag. The last member of the SCROLLINFO 
structure, 1TrackPos, isn’t used by the SetScrollinfo call and is ignored. 

The /Mask field can contain one last flag. Passing a SIF_DISABLENOSCROLL 
flag causes the scroll bar to be disabled, but still visible. This is handy when the en- 
tire scrolling range is visible within the viewable area and no scrolling is necessary. 
Disabling the scroll bar in this case is often preferable to simply removing the scroll 
bar completely. 

Those with a sharp eye for detail will notice a problem with the width of the 
fields in the SCROLLINFO structure. The nMin, nMax, and nPos fields are integers 
and therefore in the world of Windows CE, are 32 bits wide. On the other hand, the 
WM_HSCROLL and WM_VSCROLL messages can return only a 16-bit position in the 
high word of the wParam parameter. If you’re using scroll ranges greater than 65,535, 
use this function: 


BOOL GetScrollInfo (HWND hwnd, int fnBar, LPSCROLLINFO Ipsi); 


As with SetScrollinfo, the flags in the /nBar field indicate the window handle 
that should be passed to the function. The SCROLLINFO structure is identical to the 
one used in SetScrollInfo; however, before it can be passed to GetScrollinfo, it must 
be initialized with the size of the structure in cbSize. An application must also indi- 
cate what data it wants the function to return by setting the appropriate flags in the 
{Mask field. The flags used in fMask are the same as the ones used in SetScrollInfo 
with a couple of additions. Now a SIF_TRACKPOS flag can be passed to have the 
scroll bar return its current thumb position. When called during a WM_xSCROLL 
message, the ”TrackPos field contains the real time position while the Pos field 
contains the scroll bar position at the start of the drag of the thumb. 

The scroll bar is an unusual control in that it can be added easily to windows 
simply by specifying a window style flag. It’s also unusual in that the control is placed 
outside the client area of the window. The reason for this assistance is that scroll bars 
are commonly needed by applications, so the Windows developers made it easy to 
attach scroll bars to windows. Now let’s look at the other basic Windows controls. 


WINDOWS CONTROLS 


While scroll bars hold a special place because of their easy association with standard 
windows, there are a large number of other controls that Windows applications often 
use, including buttons, edit boxes, and list boxes. In short, controls are simply pre- 
defined window classes. Each has a custom window procedure supplied by Windows 
that gives each of these controls a tightly defined user and programming interface. 
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Since a control is just another window, it can be created with a call to 
CreateWindow or CreateWindowEx, or, as I will explain later in this chapter, auto- 
matically by the dialog manager during the creation of a dialog box. Like menus, 
controls notify the parent window of events via WM_COMMAND messages encod- 
ing events and the ID and window handle of the control encoded in the parameters 
of the message. Controls can also be configured and manipulated using predefined 
messages sent to the control. Among other things, applications can set the state of 
buttons, add or delete items to list boxes, and set the selection of text in edit boxes 
all by sending messages to the controls. » 


There are six predefined window control classes. They are 
Button A wide variety of buttons. 

Edit A window that can be used to enter or display text. 
List A window that contains a list of strings. 


Combo A combination edit box and list box. 


Static A window that displays text or graphics that a user can’t change. 


Scroll bar A scroll bar not attached to a specific window. 


Each of these controls has a wide range of function, far too much for me to cover 
completely in this chapter. But Ill quickly review these controls, mentioning at least 
the highlights. Afterward, I'll show you an example program, CtlView, to demonstrate 
these controls and their interactions with their parent windows. 


Button Controls 
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Button controls enable several forms of input to the program. Buttons come in many 
styles, including push buttons, check boxes, and radio buttons. Each style is designed 
for a specific use—for example, push buttons are designed for receiving momentary 
input, check boxes are designed for on/off input, and radio buttons allow a user to 
select one of a number of choices. 


Push buttons 

In general, push buttons are used to invoke some action. When a user presses a 
push button using a stylus, the button sends a WM_COMMAND message with a 
BN_CLICKED (for button notification clicked) notify code in the high word of the 
wParam parameter. 


Check boxes 

Check boxes display a square box and a label that asks the user to specify a choice. 
A check box retains its state, either checked or unchecked, until the user clicks 
it again or the program forces the button to change state. In addition to the standard 
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BS_CHECKBOxX< style, check boxes can come in a 3-state style, BS_3STATE, that al- 
lows the button to be disabled and shown grayed out. Two additional styles, 
BS_AUTOCHECKBOX and BS_AUTO3STATE, automatically update the state and look 
of the control to reflect the checked, unchecked, and in the case of the 3-state check 
box, the disabled state. 

As with push buttons, check boxes send a BN_CLICKED notification when the 
button is clicked. Unless the check box has one of the automatic styles, it’s the re- 
sponsibility of the application to manually change the state of the button. This can 
be done by sending a BM_SETCHECK message to the button with the wParam set to 
0 to uncheck the button or 1 to check the button. The 3-state check boxes have a 
third, disabled state that can be set by means of the BM_SETCHECK message with 
the wParam value set to 2. An application can determine the current state using the 
BM_GETCHECK message. 


Radio buttons 

Radio buttons allow a user to select from a number of choices. Radio buttons are 
grouped in a set, with only one of the set ever being checked at a time. If it’s using 
the standard BS_RADIOBUTTON style, the application is responsible for checking 
and unchecking the radio buttons so that only one is checked at a time. However, 
like check boxes, radio buttons have an alternative style, Bs_AUTORADIOBUTTON, 
that automatically maintains the group of buttons so that only one is checked. 


Group boxes 
Strangely, the group box is also a type of button. A group box appears to the user as 
a hollow box with an integrated text label surrounding a set of controls that are natu- 
rally grouped together. Group boxes are merely an organizational device and have 
no programming interface other than the text of the box, which is specified in the 
window title text upon creation of the group box. Group boxes should be created 
after the controls within the box are created. This ensures that the group box will be 
“beneath” the controls it contains in the window Z-order. 

You should also be careful when using group boxes on Windows CE devices. 
The problem isn’t with the group box itself, but with the small size of the Windows 
CE screen. Group boxes take up valuable screen real estate that can be better used 
by functional controls. This is especially the case on the Palm-size PC with its very 
small screen. In many cases, a line drawn between sets of controls can visually group 
the controls as well as a group box can. 


Customizing the appearance of a button 

You can further customize the appearance of the buttons described so far by using a 
number of additional styles. The styles, BS_RIGHT, BS_LEFT, BS_BOTTOM, and 
BS_TOP, allow you to position the button text in a place other than the default center 
of the button. The BS_MULTILINE style allows you to specify more than one line of 
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text in the button. The text is flowed to fit within the button. The newline character 
(\n) in the button text can be used to specifically define where line breaks occur. 
Windows CE doesn’t support the BS_ICON and BS_BITMAP button styles supported 
by other versions of Windows. 


Owner-draw buttons 

You can totally control the look of a button by specifying the BS_OWNERDRAYW style. 
When a button is specified as owner-draw, its owner window is entirely responsible 
for drawing the button for all the states in which it might occur. When a window 
contains an owner-draw button, it’s sent a WM_DRAWITEM message to inform it that 
a button needs to be drawn. For this message, the wParam parameter contains the 
ID value for the button and the /Param parameter points to a DRAWITEMSTRUCT 
structure defined as 


typedef struct tagDRAWITEMSTRUCT { 
UINT CtlType; 
UINT CtlID; 
UINT itemID; 
UINT itemAction; 
UINT itemState; 
HWND hwndIitem; 
HDC hDC; 
RECT rcitem; 
DWORD itemData; 

} DRAWITEMSTRUCT; 


The CilType field is set to ODT_BUTTON while the CiIID field, like the wParam 
parameter, contains the button’s ID value. The itemAction field contains flags that 
indicate what needs to be drawn and why. The most significant of these fields is 
itemState, which contains the state (selected, disabled, and so forth) of the button. 
The bDC field contains the device context handle for the button window while the 
rcItem RECT contains the dimensions of the button. The itemData field is NULL for 
owner-draw buttons. 

As you might expect, the WM_DRAWITEM handler contains a number of GDI 
calls to draw lines, rectangles, and whatever else is needed to render the button. An 
important aspect of drawing a button is matching the standard colors of the other 
windows in the system. Since these colors can change, they shouldn’t be hard coded. 
You can query to find out which are the proper colors by using the function 


DWORD GetSysColor (int nIndex); 


This function returns an RGB color value for the colors defined for different 
aspects of windows and controls in the system. Among a number of predefined in- 
dex values passed in the index parameter, an index of COLOR_BTNFACE returns the 
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proper color for the face of a button while COLOR_BTNSHADOY returns the dark 
color for creating the three-dimensional look of a button. 


The Edit Control 


The edit control is a window that allows the user to enter and edit text. As you might 
imagine, the edit control is one of the handiest controls in the Windows control pan- 
theon. The edit control is equipped with full editing capability, including cut, copy, 
and paste interaction with the system clipboard, all without assistance from the ap- 
plication. Edit controls display a single line, or by specifying the ES_MULTILINE style, 
multiple lines of text. The Notepad accessory, provided with the desktop versions of 
Windows, is simply a top-level window that contains a multiline edit control. 

The edit control has a few other features that should be mentioned. An edit 
control with the ES_PASSWORD style displays an asterisk (*) character by default 
in the control for each character typed; the control saves the real character. The 
ES_READONTLY style protects the text contained in the control so that it can be read, 
or copied into the clipboard, but not modified. The ES_LOWERCASE and ES_UPPER- 
CASE styles force characters entered into the control to be changed to the speci- 
fied case. 

You can add text to an edit control by using the WM_SETTEXT message and 
retrieve text by using the WM_GETTEXT message. Selection can be controlled using 
the EM_SETSEL message. This message specifies the starting and ending characters 
in the selected area. Other messages allow the position of the caret (the marker that 
indicates the current entry point in an edit field) to be queried and set. Multiline edit 
controls contain a number of additional messages to control scrolling as well as to 
access characters by line and column position. 


The List Box Control 


The list box control displays a list of text items so that the user might select one or 
more of the items within the list. The list box stores the text, optionally sorts the items, 
and manages the display of the items, including scrolling. List boxes can be config- 
ured to allow selection of a single item or multiple items or to prevent any selec- 
tion at all. 

You add an item to a list box by sending an LB_ADDSTRING or LB_INSERTSTRING 
message to the control, passing a pointer to the string to add in the [Param parame- 
ter. The LB_ADDSTRING message places the newly added string at the end of the list 
of items while LB_LINSERTSTRING can place the string anywhere within the list of 
items in the list box. The list box can be searched for a particular item using the 
LB_FIND message. 
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Selection status can be queried using the LB_GETCURSEL for single selection 
list boxes. For multiple selection list boxes, the LB_GETSELCOUNT and LB_GET- 
SELITEMS can be used to retrieve the items currently selected. Items in the list box 
can be selected programmatically using the LB_SETCURSEL and LB_SETSEL messages. 

Windows CE supports most of the list box functionality available in other ver- 
sions of Windows with the exception of owner-draw list boxes, and the LB_DIR 
family of messages. A new style, LBS_EX_CONSTSTRINGDATA, is supported un- 
der Windows CE. A list box with this style doesn’t store strings passed to it. Instead, 
the pointer to the string is stored and the application is responsible for maintaining 
the string. For large arrays of strings that might be loaded from a resource, this pro- 
cedure can save RAM because the list box won’t maintain a separate copy of the 
list of strings. | 


The Combo Box Control 
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The combo box is (as the name implies) a combination of controls—in this case, a 
single-line edit control and a list box. The combo box is a space-efficient control for 
selecting one item from a list of many or for providing an edit field with a list of pre- 
defined, suggested entries. Under Windows CE, the combo box comes in two styles: 
drop-down and drop-down list. (Simple combo boxes aren’t supported.) The drop- 
down style combo box contains an edit field with a button at the right end. Clicking 
on the button displays a list box that might contain more selections. Clicking on one 
of the selections fills the edit field of the combo box with the selection. The drop- 
down list style replaces the edit box with a static text control. This allows the user to 
select from an item in the list but prevents the user from entering an item that’s not in 
the list. 

Since the combo box combines the edit and list controls, a list of the messages 
used to control the combo box strongly resembles a merged list of the messages for 
the two base controls. CB_ADDSTRING, CB_INSERTSTRING, and CB_FINDSTRING 
act like their list box cousins. Likewise the CB_SETEDITSELECT and CB_GETEDIT- 
SELECT messages set and query the selected characters in the edit box of a drop- 
down or a drop-down list combo box. To control the drop-down state of a drop-down 
or drop-down list combo box, the messages CB_LSHOWDROPDOWN and CB_GET- 
DROPPEDSTATE can be used. 

As in the case of the list box, Windows CE doesn’t support owner-draw combo 
boxes. However, the combo box supports the CBS_EX_CONSTSTRINGDATA extended 
style, which instructs the combo box to store a pointer to the string for an item in- 
stead of the string itself. As with the list box LBS_EX_CONSTSTRINGDATA style, this 
procedure can save RAM if an application has a large array of strings stored in ROM 
because the combo box won’t maintain a separate copy of the list of strings. 
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Static Controls 


Static controls are windows that display text, icons, or bitmaps not intended for user 
interaction. You can use static text controls to label other controls in a window. What 
a static control displays is defined by the text and the style for the control Under 
Windows CE, static controls support the following styles: 


M SS_IEFT Displays a line of left-aligned text. The text is wrapped, if nec- 
essary, to fit inside the control. 


M SS_CENTER Displays a line of text centered in the control. The text is 
wrapped, if necessary, to fit inside the control. 


M SS_RIGHT Displays a line of text aligned with the right side of the con- 
trol. The text is wrapped, if necessary, to fit inside the control. 


M SS_LEFTNOWORDWRAP Displays a line of left-aligned text. The text isn’t 
wrapped to multiple lines. Any text extending beyond the right side of 
the control is clipped. 


M SS_BITMAP Displays a bitmap. Window text for the control specifies the 
name of the resource containing the bitmap. 


M SS_ICON Displays an icon. Window text for the control specifies the name 
of the resource containing the icon. 


Static controls with the SS_NOTIFY style send a WM_COMMAND message 
when the control is clicked, enabled, or disabled, although the Windows CE ver- 
sion of the static control doesn’t send a notification when it’s double-clicked. The 
SS_CENTERIMAGE style, used in combination with the SS_BITMAP or SS_ICON style, 
centers the image within the control. The SS_NOPREFIX style can be used in combi- 
nation with the text styles. It prevents the ampersand (&) character from being inter- 
preted as indicating the next character is an accelerator character. 

Windows CE doesn’t support static controls that display filled or hollow rect- 
angles such as those drawn with the SS_WHITEFRAME or SS_BLACKRECT styles. Also, 
Windows CE doesn’t support owner-draw static controls. 


The Scroll Bar Control 


The scroll bar control operates identically to the window scroll bars described previously 
with the exception that the fnBar field used in SetScrollInfo and GetScrollInfo must be 
set to SB_CTL. The hwnd field then must be set to the handle of the scroll bar control, 
not to the window that owns the scroll bar. Like window scroll bars, the owner of the 
scroll bar is responsible for fielding the scroll messages WM_VSCROLL and WM_HSCROLL 
and setting the new position of the scroll bar in response to these messages. 
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The CtilView Example Program 


The CtlView example program, shown in Figure 4-5, demonstrates all the controls 
I’ve just described. The example makes use of several application-defined child win- 
dows that contain various controls. You switch between the different child windows 
by clicking on one of five radio buttons displayed across the top of the main win- 
dow. As each of the controls reports a notification through a WM_COMMAND mes- 
sage, that notification is displayed in a list box on the right side of the window. CtlView 
is handy for observing just what messages a control sends to its parent window and 
when they’re sent. One problem with CtlView is that it’s designed for an H/PC screen, 
not a Palm-size PC screen. If you run CtlView on a Palm-size PC, you'll see that the 
controls don’t all fit onto the small Palm-size PC screen. 


Figure 4-5. The CilView program. 


176 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


177 


Ses 


eS 
Sees 


Sasics 


ming 


4-5. continued 


igure 


F 


178 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


179 


continued 


4-5 


igure 


F 


180 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


181 


BS cod 


. continued 


4-5 


SEES 


= 


igure 


F 


182 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


: 183 


c 


. continued 


4-5 


igure 


F 


184 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


185 


es 


aioe 


Sea 
pes 


ics 


bas 


ing 


continued 


4-5 


igure 


F 


186 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


187 


. continued 


“5 


Figure 4 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


189 


. continued 


4-5 


igure 


F 


190 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


191 


Part | 


192 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


193 


Part | 


Figure 4-5. continued 


194 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


195 


Part | 


196 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


197 


d 


continue 


4-5 


igure 


F 


198 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


199 


Figure 4-5. continued 


200 


Chapter 4 Windows, Controls, and Dialog Boxes 


(continued) 


201 


continued 


5 


igure 4 


= 
cS 
a. 


F 


Chapter 4 Windows, Controls, and Dialog Boxes 
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Figure 4-5. continued 


204 


Chapter 4 Windows, Controls, and Dialog Boxes 


When the CtlView program starts, the WM_CREATE handler of the main win- 
dow, DoCreateFrame, creates a row of radio buttons across the top of the window, 
a list box on the right side of the window, and five different child windows on the left 
side of the window. (The five child windows are all created without the WS_ VISIBLE 
style, so they’re initially hidden.) Each of the child windows in turn creates a number 
of controls. Before returning from the DoCreateFrame, CtlView checks one of the auto 
radio buttons and makes the BtnWnd child window (the window that contains the 
example button controls) visible using ShowWindow. 

As each of the controls on the child windows are tapped, clicked, or selected, the 
control sends WM_COMMAND messages to its parent window. That window in turn 
sends the information from the WM_COMMAND message to its parent, the frame win- 
dow, using the application-defined message MYMSG_ADDLINE. There the notification 
data is formatted and displayed in the list box on the right side of the frame window. 
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_ The other function of the frame window is to switch between the different child 
windows. The application accomplishes this by displaying only the child window that 
matches the selection of the radio buttons across the top of the frame window. The 
processing for this is done in the WM_COMMAND handler, DoCommandFrame in 
CtlView.c. | 

The best way to discover how and when these controls send notifications is to 
run the example program and use each of the controls. Figure 4-6 shows the Ctl View 
window with the button controls displayed. As each of the buttons is clicked, a 
BN_CLICKED notification is sent to the parent window of the control. The parent 
window simply labels the notification and forwards it to the display list box. Be- 
cause the Check Box button isn’t an auto check box, Ctl View must manually change 
the state of the check box when a user clicks it. The other check boxes and radio 
buttons, however, do automatically change state because they were created with 
the BS_AUTOCHECKBOX, BS_AUTO3STATE, and BS_AUTORADIOBUTTON styles. 
The square button with the exclamation mark inside a triangular icon is an owner- 
draw button. 


EN_UPDATE 

EN_CHANGE 

WM_DRAWITEM Action:1 State:0 
BN_SETFOCUS 

BN_CLICKED 

BN_KILLFOCUS 


| [7] Auto 3-state box BN_CLICKED 
| @ Auto radio button 
1 © Auto radio button 


Figure 4-6. The CilView window with the button child window displayed in 
the left pane. 


The source code for each child window is contained in a separate file. The source 
for the window containing the button controls is contained in BtnWnd.c. The file 
contains an initialization routine UnitBtn Wnd) that registers the window and a win- 
dow procedure (BinWndProc) for the window itself. The button controls themselves 
are created during the WM_CREATE message using CreateWindow. The position, style, 
and other aspects of each control are contained in an array of structures named Bins. 
The DoCreateBinWnd function cycles through each of the entries in the array, call- 
ing CreateWindow for each one. Each child window in CtlView uses a similar pro- 
cess to create its controls. | 

To support the owner-draw button, BtnWndProc must handle the WM_DRAW- 
ITEM message. The WM_DRAWITEM message is sent when the button needs to be 
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drawn because it has changed state, gained or lost the focus, or because it has been 
uncovered. Although the DrawButton function (called each time a WM_DRAWITEM 
message is received) expends a great deal of effort to make the button look like a 
standard button, there’s no reason a button can’t have any look you want. 

The other window procedures provide only basic support for their controls. The 
WM_COMMAND handlers simply reflect the notifications back to the main window. 
The ScrollWnd child window procedure, ScrollWndProc, handles WM_VSCROLL and 
WM_HSCROLL messages because that’s how scroll bar controls communicate with 
their parent windows. 


Controls and colors 
Finally, a word about colors. A large number of Windows CE devices use a gray-scale 
display instead of a color display, including all of the first generation H/PC and Palm- 
size PC systems. This has made many Windows CE developers, including me, some- 
what lazy in managing color in our Windows CE programs. Now that newer Windows 
CE systems sport color displays, we have to think a bit more. 

In CtlView, the frame window class is registered in a subtly different way from 
the way I’ve registered it in previous programs. In the CtlView example, I set the 
background brush for the frame window using the line 


wc. hbrBackground = (HBRUSH)GetSysColorBrush (COLOR_STATIC); 


This sets the background color of the frame window to the same background color I 
used to draw the radio buttons. The function GetSysColorBrush returns a brush that 
matches the color used by the system to draw various objects in the system. In this 
case, the constant COLOR_STATIC is passed to GetSysColorBrush, which then returns 
the background color Windows uses when drawing static text and the text for check 
box and radio buttons. This makes the frame window background match the static 
text background. 

In the window that contains the button controls, the check box and radio but- 
ton background is changed to match the white background of the button window, 
by fielding the WM_CTLCOLORSTATIC message. This message is sent to the parent 
of a static control or a button control when the button is a check box or radio button 
to ask the parent which colors to use when drawing the control. In CtlView, the but- 
ton window returns the handle to a white brush so that the control background will 
match the white background of the window. Modifying the color of a push button is 
done by fielding the WM_CTLCOLORBUTTON message. Other controls send differ- 
ent WM_CTLCOLORxxx messages so that the colors used to draw them can be modi- 
fied by the parent window. 
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The CtlView example program demonstrates a complex use of controls. While CtlView 
creates these controls for demonstration purposes, controls are generally used to query 
user input. As CtlView demonstrates, a fair amount of code is necessary for creating 
and placing the controls in the windows. Fortunately, you don’t need this code be- 
cause Windows provides a service for exactly this purpose: dialog boxes. Dialog boxes 
query data from the user or present data to the user, hence the term dialog box. 

Dialog boxes are windows created by Windows using a template provided by 
an application. The template describes the type and placement of the controls in the 
window. The Dialog Manager—the part of Windows that creates and manages dialog 
boxes—also provides default functionality for switching focus between the controls 
using the Tab key as well as default actions for the Enter and Escape keys. In addition, 
Windows provides a default dialog box window class, freeing applications from the 
necessity of registering a window class for each of the dialog boxes it might create. 

Dialog boxes come in two types: modal and modeless. A modal dialog prevents 
the user from using the application until the dialog box has been dismissed. For ex- 
ample, the File Open and the Print dialog boxes are modal. A modeless dialog box 
can be used interactively with the remainder of the application. The Find dialog box 
in Microsoft Pocket Word is modeless; the user doesn’t need to dismiss it before typ- 
ing in the main window. 

Like other windows, dialog boxes have a window procedure, although the dia- 
log box window procedure is constructed somewhat differently from standard win- 
dows procedures. Instead of passing unprocessed messages to DefWindowProc for 
default processing, a dialog box procedure returns TRUE if it processed the message 
and FALSE if it didn’t process the message. Windows supplies a default procedure, 
DefDialogProc, for use in specific cases—that is, for specialized modeless dialog boxes 
that have their own window classes. 


Dialog Box Resource Templates 
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Most of the time, the description for the size and placement of the dialog box and for 
the controls is provided via a resource called a dialog template. You can create a dia- 
log template in memory, but unless a program has an overriding need to format the 
size and shape of the dialog box on the fly, loading a dialog template directly from a 
resource is a much better choice. As is the case for other resources such as menus, 
dialog templates are contained in the resource (RC) file. The template is referenced 
by the application using either its name or its resource ID. Here is a dialog template 
for a simple dialog box: 
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GetVal DIALOG discardable 10, 10, 75, 60 

STYLE WS_POPUP | WS_VISIBLE | WS_CAPTION | WS_SYSMENU | DS_CENTER 
EXSTYLE WS_EX_CAPTIONOKBTN 

CAPTION “Enter line number” 


BEGIN 
LTEXT “Enter &value:" IDD_VALLABEL, 5, 10, 40, 12 
EDITTEXT IDD_VALUE, 50, 10, 20, 12, WS_TABSTOP 


AUTORADIOBUTTON "&Decimal", IDD_DEC, By.' 204 “BUG. 12% 
WS_TABSTOP | WS_GROUP 
AUTORADIOBUTTON "&Hex", IDD_HEX, 5, 40, 60, 12 
END 


The syntax for a dialog template follows a simple pattern similar to that for a 
menu resource. First is the name or ID of the resource followed by the keyword DIA- 
LOG identifying that what follows is a dialog template. The optional discardable 
keyword is followed by the position and size of the dialog box. The position speci- 
fied is, by default, relative to the owner window of the dialog box. 

The units of measurement in a dialog box aren’t pixels but dialog units. A dia- 
log unit is defined as one quarter of the average width of the characters in the system 
font for horizontal units and one eighth of the height of one character from the same 
font for vertical units. The goal is to create a unit of measurement independent of the 
display technology; in practice, dialog boxes still need to be tested in all display reso- 
lutions in which the box might be displayed. You can compute a pixel vs. dialog unit 
conversion using the GetDialogBaseUnits function but you'll rarely find it necessary. 
The visual tools that come with most compilers these days isolate a programmer from 
terms like dialog units but it’s still a good idea to know just how dialog boxes are 
described in an RC file. 

The STYLE line of code specifies the style flags for the dialog box. The styles 
include the standard window (WS_.xx) style flags used for windows as well as a se- 
ries of dialog (DS_xx) style flags specific to dialog boxes. Windows CE supports the 
following dialog box styles: 


M DS_ABSALIGN Places the dialog box relative to the upper left corner of 
the screen instead of basing the position on the owner window. 


M DS_CENTER Centers the dialog box vertically and horizontally on the 
screen. 


M DS_MODALFRAME Creates a dialog box with a modal dialog box frame 
that can be combined with a title bar and System menu by specifying the 
WS_CAPTION and WS_SYSMENU styles. 
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M DS_SETFONT ‘Tells Windows to use a nondefault font that is specified 
in the dialog template. 


mM $DS_SETFOREGROUND Brings the dialog box to the foreground after it’s 
created. If an application not in the foreground displays a dialog box, 
this style forces the dialog box to the top of the Z-order so that the user 


will see it. 


Most dialog boxes are created with at least some combination of the WS_POPUP, 
WS_CAPTION, and WS_SYSMENU style flags. The WS_POPUP flag indicates the dia- 
log box is a top-level window. The WS_CAPTION style gives the dialog box a title 
bar. A title bar allows the user to drag the dialog box around as well as serving as a 
site for title text for the dialog box. The WS_SYSMENU style causes the dialog box to 
have a Close button on the right end of the title bar, thus eliminating the need for a 
command bar control to provide the Close button. Note that Windows CE uses this 
flag differently from other versions of Windows, in which the flag indicates that a system 
menu is to be placed on the end of the title bar. 

The EXSTYLE line of code specifies the extended style flags for the dialog box. 
For Windows CE, these flags are particularly important. The WS_EX_CAPTIONOKBTN 
flag tells the dialog manager to place an OK button on the title bar to the immediate 
left of the Close button. Having both OK and Close (or Cancel) buttons on the title 
bar saves precious space in dialog boxes that are displayed on the small screens typical 
of Windows CE devices. The WS_EX_CONTEXTHELP extended style places a Help 
button on the title bar to the immediate left of the OK button. Clicking on this but- 
ton results in a WM_HELP message being sent to the dialog box procedure. 

The CAPTION line of code specifies the title bar text of the dialog, providing 
that the WS_CAPTION style was specified so that the dialog box will have a title bar. 

The lines describing the type and placement of the controls in the dialog box 
are enclosed in BEGIN and END keywords. Each control is specified either by a par- 
ticular keyword, in the case of commonly used controls, or by the keyword CON- 
TROL, which is a generic placeholder that can specify any window class to be placed 
in the dialog box. The LTEXT line of code on page 209 specifies a static left-justified 
text control. The keyword is followed by the default text for the control in quotes. 
The next parameter is the ID of the control, which must be unique for the dialog box. 
In this template, the ID is a constant defined in an include file that is included by 
both the resource script and the C or C++ file containing the dialog box procedure. 


Chapter 4 Windows, Controls, and Dialog Boxes 


The next four values are the location and size of the control, in dialog units, 
relative to the upper left corner of the dialog box. Following that, any explicit style 
flags can be specified for the control. In the case of the LTEXT line, no style flags are 
necessary, but as you can see the EDITTEXT and first AUTORADIOBUTTON entries 
each have style flags specified. Each of the control keywords have subtly different 
syntax. For example, the EDITTEXT line doesn’t have a field for default text. The style 
flags for the individual controls deserve notice. The edit control and the first of the 
two radio buttons have a WS_TABSTOP style. The dialog manager looks for controls 
with the WS_TABSTOP style to determine which control gets focus when the user 
presses the Tab. In this example, pressing the Tab key results in focus being switched 
between the edit control and the first radio button. 

The WS_GROUP style on the first radio button starts a new group of controls. 
All the controls following the radio button are grouped together, up to the next con- 
trol that has the WS_GROUP style. Grouping auto radio buttons allow only one radio 
button at a time to be selected. 

Another benefit of grouping is that focus can be changed among the controls 
within a group by exploiting the cursor keys as well as the Tab key. The first mem- 
ber of a group should have a WS_TABSTOP style; this allows the user to tab to the 
group of controls and then use the cursor keys to switch the focus among the con- 
trols in the group. 

The CONTROL statement isn’t used in this example, but it’s important and merits 
some explanation. It’s a generic statement that allows inclusion of any window class 
in a dialog box. It has the following syntax: 


CONTROL “text", id, class, style, x, y, width, height 
[, extended-style] 


For this entry, the default text and control ID are similar to the other statements 
but the next field, class, is new. It specifies the window class of the control you want 
to place in the dialog box. The class field is followed by the style flags, then the loca- 
tion and size of your control. Finally, the CONTROL statement has a field for extended 
style flags. If you use Microsoft Developer Studio to create a dialog box and look at 
the resulting RC file using a text editor, you'll see that Developer Studio uses CON- 
TROL statements instead of the more readable LTEXT, EDITTEXT, and BUTTON state- 
ments. There’s no functional difference between an edit control created with a 
CONTROL statement and one created with an EDITTEXT statement. The CONTROL 
statement is a generic version of the more specific keywords. The CONTROL state- 
ment also allows inclusion of controls that don’t have a special keyword associated 
with them. 
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Creating and displaying a dialog box is simple; just use one of the many dialog box 


ta La +4 Th £; +t tern n* +h aon. 
creation TuNnCcTIONS. ine first TWO are tnese: 


int DialogBox (HANDLE hInstance, LPCTSTR IpTemplate, HWND hWndOwner, 
DLGPROC 1pDialogFunc); 


int DialogBoxParam (HINSTANCE hInstance, LPCTSTR IpTemplate, 
HWND hWndOwner, DLGPROC IpDialogFunc, 
LPARAM dwInitParam) ; 


These two functions differ only in DialogBoxParam’s additional LPARAM pa- 
rameter, so I’ll talk about them at the same time. The first parameter to these func- 
tions is the instance handle of the program. The second parameter specifies the name 
or ID of the resource containing the dialog template. As with other resources, to specify 
a resource ID instead of a name requires the use of the MAKEINTRESOURCE macro. 

The third parameter is the handle of the window that will own the dialog box. 
The owning window isn’t the parent of the dialog box because, were that true, the 
dialog box would be clipped to fit inside the parent. Ownership means instead that 
the dialog box will be hidden when the owner window is minimized and will always 
appear above the owner window in the Z-order. 

The fourth parameter is a pointer to the dialog box procedure for the dialog 
box. I’ll describe the dialog box procedure shortly. The DialogBoxParam function 
has a fifth parameter, which is a user-defined value that’s passed to the dialog box 
procedure when the dialog box is to be initialized. This helpful value can be used to 
pass a pointer to a structure of data that can be referenced when your application is 
initializing the dialog box controls. 

Two other dialog box creation functions create modal dialogs. They are the 
following: 


int DialogBoxIndirect (HANDLE hInstance, LPDLGTEMPLATE IpTemplate, 
HWND hWndParent, DLGPROC IpDialogFunc) ; 


int DialogBoxIndirectParam (HINSTANCE hInstance, | 
LPCDLGTEMPLATE DialogTemplate, HWND hWndParent, 
DLGPROC 1pDialogFunc, LPARAM dwInitParam) ; 


The difference between these two functions and the two previously described 
is that these two use a dialog box template in memory to define the dialog box rather 
than using a resource. This allows a program to dynamically create a dialog box tem- 
plate on the fly. The second parameter to these functions points to a DLGTEMPLATE 
structure, which describes the overall dialog box window, followed by an array of 
DLGITEMTEMPLATE structures defining the individual controls. 


Chapter 4 Windows, Controls, and Dialog Boxes 


When any of these four functions are called, the dialog manager creates a modal 
dialog box using the template passed. The window that owns the dialog is disabled 
and the dialog manager then enters its own internal GetMessage/DispatchMessage 
message processing loop; this loop doesn’t exit until the dialog box is destroyed. 
Because of this, these functions don’t return to the caller until the dialog box has been 
destroyed. The WM_ENTERIDLE message that’s sent to owner windows in other ver- 
sions of Windows while the dialog box is displayed isn’t supported under Windows CE. 

If an application wanted to create a modal dialog box with the template shown 
above and pass a value to the dialog box procedure it might call this: 


DialogBoxParam (hInstance, TEXT ("GetVal"), hWnd, GetValDlgProc, 
Qx1234); 


The hbInstance and hWnd parameters would be the instance handle of the applica- 
tion and the handle of the owner window. The GetVal string is the name of the dia- 
log box template while GetValDlgProc is the name of the dialog box procedure. Finally, 
0x1234 is an application-defined value. In this case, it might be used to provide a 
default value in the dialog box. 


Dialog Box Procedures 


The final component necessary for a dialog box is the dialog box procedure. As in 
the case of a window procedure, the purpose of the dialog box procedure is to field 
messages sent to the window—in this case, a dialog box window—and perform the 
appropriate processing. In fact, a dialog box procedure is simply a special case of a 
window procedure, although we should pay attention to a few differences between 
the two. 

The first difference, as mentioned in the previous section, is that a dialog box 
procedure doesn’t pass unprocessed messages to DefWindowProc. Instead, the pro- 
cedure returns TRUE for messages it processes and FALSE for messages that it doesn’t 
process. The dialog manager uses this return value to determine whether the mes- 
sage needs to be passed to the default dialog box procedure. 

The second difference from standard window procedures is the addition of a 
new message, WM_INITDIALOG. Dialog box procedures perform any initialization 
of the controls during the processing of this message. Also, if the dialog box was created 
with DialogBoxParam or DialogBoxIndirectParam, the lParam value is the generic 
parameter passed during the call that created the dialog box. While it might seem 
that the controls could be initialized during the WM_CREATE message, that doesn’t 
work. The problem is that during the WM_CREATE message, the controls on the dia- 
log box haven’t yet been created, so they can’t be initialized. The WM_INITDIALOG 
message is sent after the controls have been created and before the dialog box is made 
visible, which is the perfect time to initialize the controls. 
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Here are a few other minor differences between a window procedure and a 
dialog box procedure. Most dialog box procedures don’t need to process the 
WM_PAINT message because any necessary painting is done by the controls or, in 
the case of owner-draw controls, in response to control requests. Most of the code in 
a dialog box procedure is responding to WM_COMMAND messages from the con- 
trols. As with menus, the WM_COMMAND messages are parsed by the control ID 
values. Two special predefined ID values that a dialog box has to deal with are IDOK 
and IDCANCEL. IDOK is assigned to the OK button on the title bar of the dialog box 
while IDCANCEL is assigned to the Close button. In response to a click of either button, 


a dialog box procedure should call 
BOOL EndDialog (HWND hDlg, int nResult); 


EndDialog closes the dialog box and returns control to the caller of whatever func- 
tion created the dialog box. The /Dig parameter is the handle of the dialog box while 
the Result parameter is the value that’s passed back as the return value of the func- 
tion that created the dialog box. 

The difference, of course, between handling the IDOK and IDCANCEL buttons 
is that if the OK button is clicked, the dialog box procedure should collect any rele- 
vant data from the dialog box controls to return to the calling procedure before it 
calls EndDialog. 

A dialog box procedure to handle the GetVal template previously described is 
shown here: 


// GetVal Dialog procedure 
// 
BOOL CALLBACK GetValDlgProc (HWND hWnd, UINT wMsg, WPARAM wParam, 
LPARAM 1Param) { 
TCHAR szText[64]; 
INT nVal, nBase; 


Switch (wMsg) { 
case WM_INITDIALOG: 
SetDigItemInt (hWnd, IDD_VALUE, @, TRUE); 
SendDlgItemMessage (hWnd, IDD_VALUE, EM_LIMITTEXT, 
sizeof (szText)-1, 0); 
CheckRadioButton (hWnd, IDD_DEC, IDD_HEX, IDD_DEC); 
return TRUE; 


case WM_COMMAND: 
switch (LOWORD (wParam)) { 


case IDD_HEX: 
// See if Hex already checked. 
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if (SendDigItemMessage (hWnd, IDD_HEX, 
BM_GETSTATE, 8, @) == BST_CHECKED) 
return TRUE; 


// Get text from edit control. 
GetDilgItemText (hWnd, IDD_VALUE, szText, 
sizeof (szText)); 
// Convert value from decimal, then set as hex. 
if (ConvertValue (szText, 10, &nVal)) { 
// If conversion successful, set new value. 
wsprintf (szText, TEXT ("%X"), nVal); 
SetDlgItemText (hWnd, IDD_VALUE, szText); 
// Set radio button. 
CheckRadioButton (hWnd, IDD_DEC, IDD_HEX, 
IDD_HEX); 
} else { 
MessageBox (hWnd, 
TEXT ("Value not valid"), 
TEXT ("Error"), MB_OK); 
; ; 
return TRUE; 


case IDD_DEC: 
// See if Dec already checked. 
if (SendDlgItemMessage (hWnd, IDD_DEC, 
BM_GETSTATE, ®, @) == BST_CHECKED) 
return TRUE; 


// Get text from edit control. 
GetDlgItemText (hWnd, IDD_VALUE, szText, 
sizeof (szText)); 
// Convert value from hex, then set as decimal. 
if (ConvertValue (szText, 16, &nVal)) { 
// If conversion successful, set new value. 
wsprintf (szText, TEXT ("%d"), nVal);. 
SetDigItemText (hWnd, IDD_VALUE, szText); 
// Set radio button. 
CheckRadioButton (hWnd, IDD_DEC, IDD_HEX, 
IDD_DEC) ; 
} else { 
// If bad conversion, tell user. 
MessageBox (hWnd, 
TEXT ("Value not valid"), 
TEXT ("Error"), MB_OK); 
I 
return TRUE; 


(continued) 
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case IDOK: 
// Get the current text. 
GetDlgItemText (hWnd, IDD_VALUE, szText, 
sizeof (szText)); 
// See which radio button checked. 
if (SendDigItemMessage (hWnd, IDD_DEC, 
BM_GETSTATE, @, @) == BST_CHECKED) 
nBase = 10; 
else 
nBase = 16; 
// Convert the string to a number. 
if (ConvertValue (szText, nBase, &nVal)) 
EndDialog (hWnd, nVal); 
else 
MessageBox (hWnd, 
TEXT ("Value not valid"), 
TEXT ("Error"), MB_OK); 
break; 


case IDCANCEL: 
EndDialog (hWnd, Q); 
return TRUE; 
} 


break; 
} 
return FALSE; 


This is a typical example of a dialog box procedure for a simple dialog box. 
The only messages that are processed are the WM_INITDIALOG and WM_COMMAND 
messages. The WM_INITDIALOG message is used to initialize the edit control using 
a number passed, via DialogBoxParam, through to the /Param value. The radio but- 
ton controls aren’t auto radio buttons because the dialog box procedure needs to 
prevent the buttons from changing if the value in the entry field is invalid. The 
WM_COMMAND message is parsed by the control ID where the appropriate processing 
takes place. The IDOK and IDCANCEL buttons aren’t in the dialog box template; as 
mentioned earlier, those buttons are placed by the dialog manager in the title bar of 
the dialog box. 


Modeless Dialog Boxes 


216 


I’ve talked so far about modal dialog boxes that prevent the user from using other 
parts of the application before the dialog box is dismissed. Modeless dialog boxes, 
on the other hand, allow the user to work with other parts of the application while 
the dialog box is still open. Creating and using modeless dialog boxes requires a bit 
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more work. For example, you create modeless dialog boxes using different functions 
than those for modal dialog boxes: 


HWND CreateDialog (HINSTANCE hInstance, LPCTSTR IpTemplate, 
HWND hWndOwner, DLGPROC IpDialogFunc); 


HWND CreateDialogIndirect (HINSTANCE hInstance, LPCDLGTEMPLATE lpTemplate, 
HWND hWndOwner, DLGPROC 1lpDialogFunc); 


HWND CreateDialogIndirect (HINSTANCE hInstance, 
LPCDLGTEMPLATE IpTemplate, HWND hWndOwner, 
DLGPROC 1IpDialogFunc); 


Or 


HWND CreateDialogIndirectParam (HINSTANCE hInstance, 
LPCDLGTEMPLATE lpTemplate, HWND hWndOwner, 
DLGPROC 1pDialogFunc, LPARAM 1ParamInit); 


The parameters in these functions mirror the creation functions for the modal dialog 
boxes with similar parameters. The difference is that these functions return immedi- 
ately after creating the dialog boxes. Each function returns 0 if the create failed or 
returns the handle to the dialog box window if the create succeeded. 

The handle returned after a successful creation is important because applica- 
tions that use modeless dialog boxes must modify their message loop code to accom- 
modate the dialog box. The new message loop should look similar to the following: 


while (GetMessage (&msg, NULL, 0, @)) { 
if (ChMIDIg == 0) || (!IsDialogMessage (hMID1g, &msg))) { 
TranslateMessage (&msg); 
DispatchMessage (&msg); 


The difference from a modal dialog box message loop is that if the modeless 
dialog box is being displayed, messages should be checked to see whether they’re 
dialog messages. If they’re not dialog messages, your application forwards them to 
TranslateMessage and DispaichMessage. The code shown above simply checks to see 
whether the dialog box exists by checking a global variable containing the handle to 
the modeless dialog box and, if it’s not 0, calls IsDialogMessage. If IsDialogMessage 
doesn’t translate and dispatch the message itself, the message is sent to the standard 
TranslateMessage/DispatchMessage body of the message loop. Of course, this code 
assumes that the handle returned by CreateDialog (or whatever function creates 
the dialog box) is saved in bMIDig and that bMIDig is set to 0 when the dialog box 
is closed. 


217 


Part | 


Another difference between modal and modeless dialog boxes is in the dialog 
box procedure. Instead of using EndDialog to close the dialog box, you must call 
DestroyWindow instead. This is because EndDialog is designed to work only with 
the internal message loop processing that’s performed with a modal dialog box. Fi- 
nally, an application usually won’t want more than one instance of a modeless dia- 
log box displayed at a time. An easy way to prevent this is to check the global copy 
of the window handle to see whether it’s nonzero before calling CreateDialog. To 


do this, the dialog box Bre must set the global handle to 0 after it calls 
DestroyWindow. 


Property Sheets 


To the user, a property sheet is a dialog box with one or more tabs across the top that 
allow the user to switch among different “pages” of the dialog box. To the program- 
mer, a property sheet is a series of stacked dialog boxes. Only the top dialog box is 
visible; the dialog manager is responsible for displaying the dialog box associated 
with the tab on which the user clicks. However you approach property sheets, they’re 
invaluable given the limited screen size of Windows CE devices. 

Each page of the property sheet, named appropriately enough a property page, 
is a dialog box template, either loaded from a resource or created dynamically in 
memory. Each property page has its own dialog box procedure. The frame around 
the property sheets is maintained by the dialog manager, so the advantages of prop- 
erty sheets come with little overhead to the programmer. Unlike the property sheets 
supported in other versions of Windows, the property sheets in Windows CE don’t 
support the Apply button. Also, the OK and Cancel buttons for the property sheet 
are contained in the title bar, not positioned below the pages. 


_ Creating a property sheet 


Instead of using the dialog box creation functions to create a property sheet, a new 
function is used: 


int PropertySheet (LPCPROPSHEETHEADER Ippsph); 


The PropertySheet function creates the property sheet according to the information 
contained in the PROPSHEETHEADER structure which is defined as the following: 


typedef struct _PROPSHEETHEADER { 
DWORD dwSize; 
DWORD dwFlags; 
HWND hwndOwner; 
HINSTANCE hInstance; 
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union { 
HICON hIcon; 
LPCWSTR pszIcon; 
ie 
LPCWSTR pszCaption; 
UINT nPages; 
union { 
UINT nStartPage; 
LPCWSTR pStartPage; 


+3 
union { 
LPCPROPSHEETPAGE ppsp; 
HPROPSHEETPAGE FAR *phpage; 
}: 


PFNPROPSHEETCALLBACK pfnCallback; 
} PROPSHEETHEADER; 


Filling in this convoluted structure isn’t as imposing a task as it might look. The 
dwsSize field is the standard size field that must be initialized with the size of the struc- 
ture. The dwFlags field contains the creation flags that define how the property sheet 
is created, which fields of the structure are valid, and how the property sheet behaves. 
Some of the flags indicate which fields in the structure are used. (1’ll talk about those 
flags when I describe the other fields.) Two other flags set the behavior of the prop- 
erty sheet. The PSH_PROPTITLE flag appends the string “Properties” to the end of 
the caption specified in the pszCaption field. The PSH_MODELESS flag causes the 
PropertySheet function to create a modeless property sheet and immediately return. 
A modeless property sheet is like a modeless dialog box; it allows the user to switch 
back to the original window while the property sheet is still being displayed. 

The next two fields are the handle of the owner window and the instance handle 
of the application. Neither the blcon or pszicon fields are used in Windows CE so 
they should be set to 0. The pszCaption field should point to the title bar text for the 
property sheet. The nStartPage/pStartPage union should be set to indicate the page 
that should be initially displayed. This can be selected either by number or by title if 
the PSH_USEPSTARTPAGE flag is set in the dwFlags field. 

The ppsp/phpage union points to either an array of PROPSHEETPAGE structures 
describing each of the property pages or handles to previously created property pages. 
For either of these, the Pages field must be set to the number of entries of the array 
of structures or page handles. To indicate that the pointer points to an array of 
PROPSHEETPAGE structures, set the PSH_PROPSHEETPAGE flag in the dwFlags field. 
I'll describe both the structure and how to create individual pages shortly. 
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The p/nCallBack field is an optional pointer to a procedure that’s called twice— 
when the property sheet is about to be created and again when it’s about to be ini- 
tialized. The callback function allows applications to fine-tune the appearance of the 


property sheet for the rare times when it’s necessary. This field is ignored unless the 
PSP_USECALLBACK flag is set in the dwFlags field. 


Creating a property page 

As I mentioned earlier, individual property pages can be specified by an array of 
PROPSHEETPAGE structures or an array of handles to existing property pages. Cre- 
ating a property page is accomplished with a call to the following: 


HPROPSHEETPAGE CreatePropertySheetPage (LPCPROPSHEETPAGE Ippsp); 


This function is passed a pointer to the same PROPSHEETPAGE structure and returns 
a handle to a property page. PROPSHEETPAGE is defined as this: 


typedef struct _PROPSHEETPAGE { 
DWORD dwSize; 
DWORD dwFlags; 
HINSTANCE hInstance; 
union { 
LPCSTR pszTemplate; 
LPCDLGTEMPLATE pResource; 


y 
union { 
HICON hIcon; 
LPCSTR pszicon; 
}; 


LPCSTR pszTitle; 
DLGPROC pfnD1IgProc; 
LPARAM 1Param; 
LPFNPSPCALLBACK pfnCallback; 
UINT FAR * pcRefParent; 

} PROPSHEETPAGE; 


The structure looks similar to the PROPSHEETHEADER structure, leading with 
a dwSize and dwFlags field followed by an binstance field. In this structure, bInstance 
is the handle of the module from which the resources will be loaded. The dwFlags 
field again specifies which fields of the structure are used and how they’re used, as 
well as a few flags specifying the characteristics of the page itself. 

The pszTemplate/pResource union specifies the dialog box template used to 
define the page. If the PSP_DLGINDIRECT flag is set in the dwFlags field, the union 
points to a dialog box template in memory. Otherwise, the field specifies the name 
of a dialog box resource. The bicon/pszIcon union isn’t used in Windows CE and 


Chapter 4 Windows, Controls, and Dialog Boxes 


should be set to 0. If the dwFlags field contains a PSP_USETITLE flag, the pszT7itle 
field points to the text used on the tab for the page. Otherwise, the tab text is taken 
from the caption field in the dialog box template. The pfnDigProc field points to the 
dialog box procedure for this specific page and the /Param field is an application- 
defined parameter that can be used to pass data to the dialog box procedure. The 
DfnCallback field can point to a callback procedure that’s called twice— when the 
page is about to be created and when it’s about to be destroyed. Again, like the call- 
back for the property sheet, the property page callback allows applications to fine- 
tune the page characteristics. This field is ignored unless the dwFlags field contains 
the PSP_USECALLBACK flag. Finally, the pcRefCount field can contain a pointer to 
an integer that will store a reference count for the page. This field is ignored unless 
the flags field contains the PSP_USEREFPARENT flag. 

Windows CE supports a new flag for property pages, PSP_PREMATURE. This 
flag causes a property page to be created when the property sheet that owns it is 
created. Normally, a property page isn’t created until the first time it’s shown. This 
has an impact on property pages that communicate and cooperate with each other. 
Without the PSP_PREMATURE flag, the only property page that’s automatically cre- 
ated when the property sheet is created is the page that is displayed first. So, at that 
moment, that first page has no sibling pages to communicate with. Using the 
PSP_PREMATURE flag, you can ensure that a page is created when the property sheet 
is created even though it isn’t the first page in the sheet. While it’s easy to get over- 
whelmed with all these structures, simply using the default values and not using the 
optional fields results in a powerful and easily maintainable property sheet that’s also 
as easy to construct as a set of individual dialog boxes. 

Once a property sheet has been created, the application can add and delete 
pages. The application adds a page by sending a PSM_ADDPAGE message to the 
property sheet window. The message must contain the handle of a previously cre- 
ated property page in /Param; wParam isn’t used. Likewise, the application can re- 
move a page by sending a PPM_REMOVEPAGE message to the property sheet window. 
The application specifies a page for deletion either by setting wParam to the zero- 
based index of the page selected for removal or by passing the handle to that page in 
lParam. 

The code below creates a simple property sheet with three pages. Each of the 
pages references a dialog box template resource. As you can see, most of the initiali- 
zation of the structures can be performed in a fairly mechanical fashion. 


PROPSHEETHEADER psh; 
PROPSHEETPAGE psp[3]; 
INT 7; 


(continued) 
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// Init page structures with generic information. 
memset (&psp, @, sizeof (psp)); // Zero out all unused values. 
for (i = 0; i < dim(psp); i++) { 


SRRPANRO IEP r Tr ars. 


pspLi].dwSize = sizeof (PROPSHEETPAGE); 


pspLi].dwFlags = PSP_DEFAULT; // No special processing needed 
pspLi].hInstance = hInst; // Instance handle where the 
} // dialog templates are located 


// Now do the page specific stuff. 
pspl@].pszTemplate = TEXT ("Pagel"); // Name of dialog resource for page 1 
psplL@].pfnDIlgProc = PagelDlgProc; // Pointer to dialog proc for page 1 


pspLl1].pszTemplate = TEXT ("Page2"); // Name of dialog resource for page 2 
pspll].pfnDlgProc = Page2DlgProc; // Pointer to dialog proc for page 2 


psplL2].pszTemplate = TEXT ("Page3"); // Name of dialog resource for page 3 
pspl2].pfnDlgProc = Page3DlgProc; // Pointer to dialog proc for page 3 


// Init property sheet header structure. 
psh.dwSize = sizeof (PROPSHEETHEADER) ; 
psh.dwFlags = PSH _PROPSHEETPAGE; // We are using templates not handles. 


psh.hwndParent = hWnd; // Handle of the owner window 
psh.hInstance = hInst; // Instance handle of the application 
psh.pszCaption = TEXT ("Property sheet title"); 

psh.nPages = dim(psp); // Number of pages 

psh.nStartPage = Q; // Index of page to be shown first 
psh.ppsp = psp; // Pointer to page structures 
psh.pfnCallback = Q; // We don't need a callback procedure. 


// Create property sheet. This returns when the user dismisses the sheet 
// by tapping OK or the Close button. 
ij = PropertySheet (&psh); 


While this fragment has a fair amount of structure filling, it’s boilerplate code. 
Everything not defined, such as the page dialog box resource templates and the page 
dialog box procedures, are required for dialog boxes as well as property sheets. So, 
aside from the boilerplate stuff, property sheets require little, if any, work beyond 
simple dialog boxes. 


Property page procedures 

The procedures that back up each of the property pages have only a few differences 
from standard dialog box procedures. First, as I mentioned previously, unless the 
PSP_PREMATURE flag is used, pages aren’t created immediately when the property 
sheet is created. Instead, each page is created and WM_INITDIALOG messages are 
sent only when the page is initially shown. Also, the /Param parameter doesn’t point 
to a user-defined parameter; instead, it points to the PROPSHEETPAGE structure that 
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defined the page. Of course, that structure contains a user-definable value that can 
be used to pass data to the dialog box procedure. 

Also, a property sheet procedure doesn’t field the IDOK and IDCANCEL con- 
trol IDs for the OK and Close buttons on a standard dialog box. These buttons in- 
stead are handled by the system-provided property sheet procedure that coordinates 
the display and management of each page. When the OK or Close button is tapped, 
the property sheet sends a WM_NOTIFY message to each sheet notifying them that 
one of the two buttons has been tapped and that they should acknowledge that it’s 
okay to close the property sheet. 


WM_NOTIFY 
While this is the first time I’ve mentioned the WM_NOTIFY message, it has become 
a mainstay of the new common controls added to Windows over the last few years. 
The WM_NOTIFY message is essentially a redefined WM_COMMAND message, which 
instead of encoding the reason for the message in one of the parameters passes a 
pointer to an extensible structure instead. This has allowed the WM_NOTIFY mes- 
sage to be extended and adapted for each of the controls that use it. In the case of 
property sheets, the WM_NOTIFY message is sent under a number of conditions; when 
the user taps the OK button, when the user taps the Close button, when the page 
gains or loses focus from or to another page, or when the user requests help. 

At a minimum, the WM_NOTIFY message is sent with /Param pointing to an 
NMHDrR structure defined as the following: 


typedef struct tagNMHDR { 
HWND hwndFrom; 
UINT idFrom; 
UINT code; 

} NMHDR; 


The hwndFrom field contains the handle of the window that sent the notify message. 
For property sheets, this is the property sheet window. The idFrom field contains the 
ID of the control if a control is sending the notification. Finally, the code field con- 
tains the notification code. While this basic structure doesn’t contain any more infor- 
mation than the WM_COMMAND message, often this structure is extended with 
additional fields appended to the structure. The notification code then indicates what, 
if any, additional fields are appended to the notification structure. 


Switching pages 

When a user switches from one page to the next, the Dialog Manager sends a 
WM_NOTIFY message with the code PSN_KILLACTIVE to the page currently being 
displayed. The dialog box procedure should then validate the data on the page. If it’s 
permissible for the user to change the page, the dialog box procedure should then 
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set the return value of the window structure of the page to PSNRET_NOERROR and 
return TRUE. You set the PSNRET_NOERROR return field by calling SetWindowLong 
with DWL_MSGRESULT as in the following line of code: 


SetWindowLong (hwndPage, DWL_MSGRESULT, PSNRET_NOERROR) ; 


where hwndPage is the handle of the property sheet page. A page can keep focus by 
returning PSNRET_INVALID_NOCHANGEPAGE in the return field. Assuming a page 
has indicated that it’s okay to lose focus, the page being switched to receives a 
PSN_SETACTIVE notification via a WM_NOTIFY message. The page can then accept 
the focus or specify another page that should receive the focus. 


Closing a property sheet _ 

When the user taps on the OK button, the property sheet procedure sends a 
WM_NOTIFY with the notification code PSN_KILLACTIVE to the page currently be- 
ing displayed followed by a WM_NOTIFY with the notification code PSN_APPLY to 
each of the pages that has been created. Each page procedure should save any data 
from the page controls when it receives the PSN_APPLY notification code. 

When the user clicks the Close button, a PSN_QUERYCANCEL notification is 
sent to the page procedure of the page currently being displayed. All this notification 
requires is that the page procedure return TRUE to prevent the close or FALSE to al- 
low the close. A further notification, PSN_RESET, is then sent to all the pages that 
have been created, indicating that the property sheet is about to be destroyed. 


Common Dialogs 


224 


In the early days of Windows, it was a rite of passage for a Windows developer to 
write his or her own File Open dialog box. A File Open dialog box is complex—it 
must display a list of the possible files from a specific directory, allow file navigation, 
and return a fully justified filename back to the application. While it was great for 
programmers to swap stories about how they struggled with their unique implemen- 
tation of a File Open dialog, it was hard on the users. Users had to learn a different 
file open interface for every Windows application. 

Windows now provides a set of common dialog boxes that perform typical func- 
tions, such as selecting a filename.to open or save or picking a color. These standard 
dialog boxes (called common dialogs) serve two purposes. First, common dialogs lift 
from developers the burden of having to create these dialog boxes from scratch. 
Second, and just as important, common dialogs provide a common interface to the 
user across different applications. (These days, Windows programmers swap horror 
stories about learning COM.) 

Windows CE 2.0 provides four common dialogs: File Open, Save As, Print, and 
Choose Color. Common dialogs, such as Find, Choose Font, and Page Setup, that are 
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available under other versions of Windows aren’t supported under Windows CE. 
Applications developed for Windows CE 1.0 or for the first release of the Palm-size 
PC must also do without the Print and Color common dialogs, but this isn’t much of 
a sacrifice because neither color screens nor printing is supported on those systems. 

The other advantage of the common dialogs is that they have a customized look 
for each platform while retaining the same programming interface. This makes it easy 
to use, say, the File Open dialog on both the H/PC and the Palm-size PC because 
the dialog box has the same interface on both systems even though the look of the 
dialog box is vastly different on the two platforms. Figure 4-7 shows the File Open 
dialog on the H/PC; Figure 4-8 shows the File Open dialog box on the Palm-size PC. 
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Figure 4-8. The File Open dialog on a Palm-size PC. 
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Instead of showing you how to use the common dialogs here, I’ll let the next 
example program, DlgDemo, show you. That program demonstrates all four supported 
common dialog boxes. 


The DigDemo Example Program 
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The DlgDemo program demonstrates basic dialog boxes, modeless dialog boxes, 
property sheets, and common dialogs. When you start DlgDemo, it displays a win- 
dow that shows the WM_COMMAND and WM_NOTIFY messages sent by the vari- 
ous controls in the dialogs, similar to the right side of the CtlView window. ‘he different 
dialogs can be opened using the various menu items. Figure 4-9 shows the Dialog 
Demo window with the property sheet dialog displayed. 
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Figure 4-9. The DigDemo window. 


The basic dialog box is a simple “about box” launched by selecting the Help 
About menu. The property sheet is launched by selecting the File Property Sheet menu. 
The property sheet dialog contains five pages corresponding to the different windows 
in the CtlView example. The common dialog boxes are launched from the File Open, 
File Save, File Color, and File Print menu items. These last two menu items are dis- 
abled when the program is run on a Palm-size PC since those common dialog boxes 
aren’t supported on that platform. The DlgDemo source code is shown in Figure 4-10. 
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Figure 4-10. The DigDemo program. (continued) 
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(continued) 
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Figure 4-10. continued 
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(continued) 
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Figure 4-10. continued 
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(continued) 
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Figure 4-10. continued 
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Figure 4-10. continued 
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Figure 4-10. continued 
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(continued) 
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Figure 4-10. continued 
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(continued) 
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Figure 4-10. continued 
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(continued) 
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(continued) 
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Figure 4-10. continued 
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Figure 4-10. continued 
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Figure 4-10. continued 
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procedures mirror the child window procedures of the CtlView example, the differ- 
ences being that the page procedures don’t have to create their controls, and they 
field the WM_INITDIALOG message to initialize the controls. The page procedures 
also use the technique of storing information in their window structures—in this case, 
the window handle of the main window of the example. This is necessary because 
the parent window of the pages is the property sheet, not the main window. The 
window handle is conveniently accessible during the WM_INITDIALOG message 
because it’s loaded into the user-definable parameter in the PROPSHEETPAGE struc- 
ture by the main window when the property sheet is created. Each page procedure 
copies the parameter from the PROPSHEETPAGE structure into the DWL_USER field 
of the window structure available to all dialog box procedures. When other messages 
are handled, the handle is then queried using GetWindowLong. The page procedures 
also field the WM_NOTIFY message so that they, too, can be reflected back to the 
main window. 

As with CtlView, the best way to learn from DlgDemo is to run the program 
and watch the different WM_COMMAND and WM_NOTIFY messages that are sent 
by the controls and the property sheet. Opening the property sheet and switching 
between the pages results in a flood of WM_NOTIFY messages informing the indi- 
vidual pages of what’s happening. It’s also interesting to note that when the OK but- 
ton is pressed on the property sheet, the PSN_APPLY messages are sent only to 
property pages that have been displayed. 

The menu handlers that display the Print and Color common dialogs work with 
a bit of a twist. Since the Palm-size PC doesn’t support these dialogs, DlgDemo can’t 
call the functions directly. That would result in these two functions being implicitly 
linked at run time. Since the Palm-size PC doesn’t have these common dialogs and 
therefore these functions, Windows CE wouldn’t be able to resolve the implicit links 
to all the functions in the program and therefore the program wouldn’t be able to 
load. So, instead of calling the functions directly, you explicitly link these functions 
in InitApp by loading the common dialog DLL using LoadLibrary and getting point- 
ers to the functions using GetProcAddress. If DlgDemo is running on a Palm-size PC, 
the GetProcAddress function fails and returns 0 for the function pointer. In 
OnCreateMain, a check is made to see whether these function pointers are 0, and if 
so, the Print and Color menu items are disabled. In the menu handler functions 
DoMainCommandColor and DoMainCommandPrint, the function pointers returned 
by GetProcAddress are used to call the functions. This extra effort isn’t necessary if 
you know your program will run only on a system that supports a specific set of func- 
tions, but every once in a while, this technique comes in handy. 
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This chapter has covered a huge amount of ground, from basic child windows to 
controis and on to dialog boxes and property sheets. My goai wasn’t to teach every- 
thing there is to know about these topics. Instead, I’ve tried to introduce these pro- 
gram elements, provide a few examples, and point out the subtle differences between 
the way they’re handled by Windows CE and the desktop versions of Windows. 

This chapter also marks the end of the introductory section, “Windows Program- 
ming Basics.” In these first four chapters, I’ve talked about fundamental Windows 
programming while also using a basic Windows CE application to introduce the con- 
cepts of the system message queue, windows, and messages. I’ve given you an over- 
view of how to paint text and graphics in a window and how to query the user for 
input. Finally, I talked about the windows hierarchy, controls, and dialog boxes. 
For the remainder of the book, I move from description of the elements common 
to both Windows CE and the desktop versions of Windows to the unique nature of 
Windows CE programming. I begin this process in Chapter 5 by talking about an- 
other set of controls, the common controls, this time with an emphasis on controls 
unique to Windows CE. 


Part I 


Chapter 5 


Common Controls 
and Windows CE 


As Microsoft Windows matured as an operating system, it became apparent that the 
basic controls provided by Windows were insufficient for the sophisticated user in- 
terfaces that users demanded. Microsoft developed a series of additional controls, called 
common controls, for their internal applications and later made the dynamic link li- 
brary (DLL) containing the controls available to application developers. Starting with 
Microsoft Windows 95 and Microsoft Windows NT 3.5, the common control library 
was bundled with the operating system. (Although this hasn’t stopped Microsoft from 
making interim releases of the DLL as the common control library was enhanced.) 
With each release of the common control DLL, new controls and new features are 
added to old controls. As a group, the common controls are less mature than the stan- 
dard Windows controls and therefore show greater differences between implemen- 
tations across the various versions of Windows. These differences aren't just between 
Microsoft Windows CE and other versions of Windows, but also between Windows NT, 
Windows 95, and Microsoft Windows 98. The functionality of the common controls 
in Windows CE tracks most closely with the common controls delivered with Win- 
dows 98, although not all of the Windows 98 features are supported. 

It isn’t the goal of this chapter to cover in depth all the common controls. That 
would take an entire book. Instead, I'll cover the controls and features of controls the 
Windows CE programmer will most often need when writing Windows CE applications. 
Pll start with the command bar and then look at the month calendar and time and date 
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picker controls. Finally, T’ll finish up with the list view control. By the end of the chap- 
ter, you might not know every common control inside and out, but you will be able to 
see how the common controls work in general. And you'll have the background to look 
at the documentation and understand the common controis not covered. 


PROGRAMMING COMMON CONTROLS 


Since the common controls are separate from the core operating system, the DLL that 
contains them must be initialized before any of the common controls can be used. 
Under all versions of Windows, including Windows CE, you can call the function 


void InitCommonControls (void); 


to load the library and register all the common control classes. 
Another function added recently to the common control library and supported 
by Windows CE is this one: 


BOOL InitCommonControlsEx (LPINITCOMMONCONTROLSEX IpInitCtrls); 


This function allows an application to load and initialize only selected common con- 
trols. This function is handy under Windows CE because loading only the necessary 
controls can reduce the memory impact. The only parameter to this function is a two- 
field structure that contains a size field and a field that contains a set of flags indicat- 
ing which common controls should be registered. Figure 5-1 shows the available flags 
and their associated controls. 


Flag Control Classes Initialized 
ICC_BAR_CLASSES Toolbar 

Status bar 

Trackbar 

Command bar 
ICC_COOL_CLASSES Rebar 
ICC_DATE_CLASSES Date and time picker 

Month calendar control 
ICC_LISTVIEW_CLASSES List view 

Header control 
ICC_PROGRESS_CLASS Progress bar control 
ICC_TAB_CLASSES Tab control 
ICC_TREEVIEW_CLASSES Tree view control 
ICC_UPDOWN_CLASS Up-down control 


Figure 5-1. Flags for selected common controls. 
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Once the common control DLL has been initialized, these controls can be treated 
as any other control. But since the common controls aren’t formally part of the Win- 
dows core functionality, an additional include file, commcetrl.h, must be included. 

The programming interface for the common controls is similar to standard Win- 
dows controls. Each of the controls has a set of custom style flags that configure the 
look and behavior of the control. Messages specific to each control are sent to con- 
figure, manipulate, and cause the control to perform actions. One major difference 
between the standard windows controls and common controls is that notifications 
of events or requests for service are sent via WM_NOTIFY messages instead of 
WM_COMMAND messages as in the standard controls. This technique allows the 
notifications to contain much more information than would be allowed using 
WM_COMMAND message notifications. 

One additional difference when programming common controls is that most of 
the control-specific messages that can be sent to the common controls have predefined 
macros that make sending the message look as if your application is calling a func- 
tion. So, instead of using an LVM_INSERTITEM message to a list view control to insert 
an item, as in 


nIndex = (int) SendMessage (hwndLV, LVM_INSERTITEM, @, (LPARAM) &lvi); 
an application could just as easily have used the line: 
nindex = ListView_InsertItem (hwndLV, &lvi); 


There’s no functional difference between the two lines; the advantage of these mac- 
ros is clarity. The macros themselves are defined in commctrl.h along with the other 
definitions required for programming the common controls. One problem with the 
macros is that the compiler doesn’t perform the type checking on the parameters that 
would normally occur if the macro were an actual function. This is also true of the 
SendMessage technique, in which the parameters must be typed as WPARAM and 
LPARAM types, but at least with messages the lack of type checking is obvious. All in 
all though, the macro route provides better readability. One exception to this system 
of macros are the calls made to the command bar control and the command bands 
control. Those controls actually have a number of true functions in addition to a large 
set of macro-wrapped messages. As a rule, I’ll talk about messages as messages, not 
as their macro equivalents. That should help differentiate what is a message or macro 
and what is a true function. 


THE COMMON CONTROLS 


Windows CE’s special niche—small personal productivity devices—has driven the re- 
quirements for the common controls in Windows CE. The frequent need for time and 
date references for schedule and task management applications has led to inclusion of 
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the date and time picker control and the month calendar control. The small screens 
of personal productivity devices inspired the space-saving command bar. Mating the 
command bar with the rebar control that was created for Internet Explorer 3.0 has 
produced the command bands coniroi. Tne command bands control provides even 
more room for menus, buttons, and other controls across the top of a Windows CE 
application. You’ve seen glimpses of the command bar control in Chapter 1 and again 
in Chapters 3 and 4. It’s time you were formally introduced. 


The Command Bar 
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Briefly, a command bar control combines a menu and a toolbar. This combination is 
valuable because, as ’ve pointed out before, the combination of a menu and toolbar 
on one line saves screen real estate on space-constrained Windows CE displays. To. 
the programmer, the command bar looks like a toolbar with a number of helper func- 
tions that make programming the command bar a breeze. In addition to the com- 
mand bar functions, you can also use most toolbar messages when you’re working 
with command bars. 

The command bands control was added to Windows CE in version 2.0. A com- 
mand bands control is a rebar control that, by default, contains a command bar in 
each band of the control. The rebar control is a fairly new common control, it’s a 
container of controls that the user can drag around the application window. It was 
previously known as a Cool Bar when it first appeared in the common control DLL 
delivered with Internet Explorer 3.0. Given that command bands are nothing more 
than command bars in a rebar control, knowing how to program a command bar is 
most of the battle when learning how to program the command bands control. 


Creating a command bar 
You build a command bar in a number of steps, each defined by a particular func- 
tion. The command bar is created, the menu is added, buttons are added, other con- 
trols are added, tool tips are added, and finally, the Close and Help buttons are 
appended to the right side of the command bar. 

You begin the process of creating a command bar with a call to 


HWND CommandBar_Create (HINSTANCE hInst, HWND hwndParent, 
int idCmdBar); 


The function requires the program’s instance handle, the handle of the parent win- 
dow, and an ID value for the control. If successful, the function returns the handle to 
the newly created command bar control. But a bare command bar isn’t much use to 
the application. It takes a menu and a few buttons jazz it up. 


Command bar menus 
You can add a menu to a command bar by calling one of two functions. The first 
function is this: 
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BOOL CommandBar_InsertMenubar (HWND hwndCB, HINSTANCE hInst, 
WORD idMenu, int iButton); 


The first two parameters of this function are the handle of the command bar and the 
instance handle of the application. The idMenu parameter is the resource ID of the 
menu to be loaded into the command bar. The last parameter is the index of the button 
to the immediate left of the menu. Because the Windows CE guidelines specify that 
the menu should be at the left end of the command bar, this parameter should be set 
to 0, which indicates that all the buttons are to the right of the menu. 

A shortcoming of the CommandBar_InsertMenubar function is that it requires 
the menu to be loaded from a resource. You can’t configure the menu on the fly. Of 
course, it would be possible to load a dummy menu and manipulate the contents of 
the menu with the various menu functions, but here’s an easier method. 

The function 


BOOL CommandBar_InsertMenubarEx (HWND hwndCB, HINSTANCE hiInst, 
LPTSTR pszMenu, int iButton); 


was added in Windows CE 2.0. The difference between CommandBar_InsertMenu- 
barEx and CommandBar_InsertMenubar is the change in the third parameter, 
pszMenu. This parameter can be either the name of a menu resource or the handle 
to a menu previously created by the program. If the pszMenu parameter is a menu 
handle, the inst parameter must be NULL. 

Once a menu has been loaded into a command bar, the handle to the menu 
can be retrieved at any time using 


HMENU CommandBar_GetMenu (HWND hwndCB, int iButton); 


The second parameter, iButton, is the index of the button to the immediate left of the 
menu. This mechanism provides the ability to identify more than one menu on the 
command bar. However, given the Windows CE design guidelines, you should see 
only one menu on the bar. With the menu handle, you can manipulate the structure 
of the menu using the many menu functions available. 

If an application modifies the menu on the command bar, the application must 
call 


BOOL CommandBar_DrawMenuBar (HWND hwndCB, int iButton); 


which forces the menu on the command bar to be redrawn. Here again, the param- 
eters are the handle to the command bar and the index of the button to the left of the 
menu. Under Windows CE, you must use CommandBar_DrawMenuBar instead of 
DrawMenuBar, which is the standard function used to redraw the menu under other 
versions of Windows. 
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Command bar buttons 

Adding buttons to a command bar is a two-step process, and is similar to adding buttons 
to a toolbar. First the bitmap images for the buttons must be added to the command 
bar. Second the buttons are added, with each of the buttons referencing one of the 
images in the bitmap list that was previously added. 

The command bar maintains its own list of bitmaps for the buttons in an inter- 
nal image list. Bitmaps can be added to this image list one at a time or as a group of 
images contained in a long and narrow bitmap. For example, for a bitmap to contain 
four 16-by-15-bit images, the dimensions of the bitmap added to the command bar 
would be 64 by 15 bits. Figure 5-2 shows this bitmap image layout. 


Image 0 Image 1 | Image 2 Image 3 
48 


0 16 32 63 


Figure 5-2. Layout of a bitmap that contains four 16-by-15-bit images. 
Loading a image bitmap is accomplished using 


int CommandBar_AddBitmap (HWND hwndCB, HINSTANCE hInst, int idBitmap, 
int iNumImages, int iReserved, int iReserved); 


This first two parameters are, as is usual with a command bar function, the handle to 
the command bar and the instance handle of the executable. The third parameter, 
idBitmap, is the resource ID of the bitmap image. The fourth parameter, iNumImages, 
should contain the number of images in the bitmap being loaded. Multiple bitmap 
images can be loaded into the same command bar by calling CommandBar_ 
AddBitmap as many times as is needed. 

Two predefined bitmaps provide a number of images that are commonly used 
in command bars and toolbars. You load these images by setting the b/nst parameter 
in CommandBar_AddBitmap to HINST_COMMCTRL and setting the idBitmap param- 
eter to either IDB_STD_SMALL_COLOR or IDB_VIEW_SMALL_COLOR. The images 
contained in these bitmaps are shown in Figure 5-3. The buttons on the top line con- 
tain the bitmaps from the standard bitmap while the second-line buttons contain the 
bitmaps from the standard view bitmap. 


Figure 5-3. Images in the two standard bitmaps provided by the common control DLL. 
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The index values to these images are defined in commctrl.h, so you don’t need 
to know the exact order in the bitmaps. The constants are 


Constants to access the standard bitmap 


STD_CUT 
STD_COPY 
STD_PASTE 
STD_UNDO 
STD_REDOW 
STD_DELETE 
STD_FILENEW 
STD_FILEOPEN 
STD_FILESAVE 
STD_PRINTPRE 


Edit/Cut button image 
Edit/Copy button image 
Edit/Paste button image 
Edit/Undo button image 
Edit/Redo button image 
Edit/Delete button image 
File/New button image 
File/Open button image 
File/Save button image 
Print preview button image 


STD_PROPERTIES Properties button image 

STD_HELP Help button (Use Commandbar_Addadornments 
function to add a help button to the 
command bar.) 


STD_FIND Find button image 
STD_REPLACE Replace button image 
STD_PRINT Print button image 


Constants to access the standard view bitmap 


VIEW_LARGEICONS View/Large Icons button image 
VIEW_SMALLICONS View/Small Icons button image 
VIEW_LIST View/List button image 
VIEW_DETAILS View/Details button image 
VIEW_SORTNAME Sort by name button image 
VIEW_SORTSIZE Sort by size button image 
VIEW_SORTDATE Sort by date button image 
VIEW_SORTTYPE Sort by type button image 
VIEW_PARENTFOLDER Go to Parent folder button image 
VIEW_NETCONNECT Connect network drive button image 
VIEW_NETDISCONNECT Disconnect network drive button image 
VIEW_NEWFOLDER Create new folder button image 


Referencing images 

The images loaded into the command bar are referenced by their index into the list 
of images. For example, if the bitmap loaded contained five images, and the image 
to be referenced was the fourth image into the bitmap, the zero-based index value 
would be 3. 

If more than one set of bitmap images was added to the command bar using 
multiple calls to CommandBar_AddBitmap, the images’ subsequent lists are refer- 
enced according to the previous count of images plus the index into that list. For 
example, if two calls were made to CommandBar_AddBitmap to add two sets of 
images, with the first call adding five images and the second adding four images, the 
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third image of the second set would be referenced with the total number of images 
added in the first bitmap (5) plus the index into the second bitmap (2) resulting in an 
index value of 5 + 2 = 7. 

Once the bitmaps have been loaded, the buttons can be added using one of 
two functions. The first function is this one: 


BOOL CommandBar_AddButtons (HWND hwndCB, UINT uNumButtons, 
LPTBBUTTON lpButtons) ; 


CommandBar_AddButtons adds a series of buttons to the command bar at one time. 
The function is passed a count of buttons and a pointer to an array of TBBUTTON 
structures. Each element of the array describes one button. The TBBUTTON structure 
is defined as the following: 


typedef struct { 

int iBitmap; 

int idCommand; 

BYTE fsState; 

BYTE fsStyle; 

DWORD dwData; 

int iString; 
} TBBUTTON; 
The iBitmap field specifies the bitmap image to be used by the button. This is, as I 
just explained, the zero-based index into the list of images. The second parameter is 
the command ID of the button. This ID value is sent via a WM_COMMAND message 
to the parent when a user clicks the button. 

The /sState field specifies the initial state of the button. The allowable values in 
this field are the following: 


| TBSTATE_ENABLED ‘The button is enabled. If this flag isn’t specified, the 
button is disabled and is grayed. 

ia TBSTATE_HIDDEN The button isn’t visible on the command bar. 

TBSTATE_PRESSED This button is displayed in a depressed state. 


a TBSTATE_CHECKED The button is initially checked. This state can be 
used only if the button has the TBSTYLE_CHECKED style. 


M ‘ZTBSTATE_INDETERMINATE ‘The button is grayed. 


One last flag is specified in the documentation, TBSTATE_WRAP, but it doesn’t 
have a valid use in a command bar. This flag is used by toolbars when a toolbar wraps 
across more than one line. 
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The /sStyle field specifies the initial style of the button, which defines how the 
button acts. The button can be defined as a standard push button, a check button, a 
drop-down button, or a check button that resembles a radio button but allows only 
one button in a group to be checked. The possible flags for the fsStyle field are the 
following: 


M <ZBSTYLE_BUTTON The button looks like a standard push button. 


M ZIBSTYLE_CHECK The button is a check button that toggles between 
checked and unchecked states each time the user clicks the button. 


zy TBSTYLE_GROUP Defines the start of a group of buttons. 


M $$ ZTBSTYLE_CHECKGROUP The button is a member of a group of check 
buttons that act like a radio buttons in that only one button in the group 
is checked at any one time. 


= TBSTYLE_DROPDOWN _ The button is a drop-down list button. 
TBSTYLE_AUTOSIZE The button’s size is defined by the button text. 


i TBSTYLE_SEP Defines a separator Ginstead of a button) that inserts a small 
space between buttons. 


The dwData field of the TBBUTTON structure is an application-defined value. 
This value can be set and queried by the application using the TB_LSETBUTTONINFO 
and TB_ GETBUTTONINFO messages. The iString field defines the index into the 
command bar string array that contains the text for the button. The iString field can 
also be filled with a pointer to a string that contains the text for the button. 

The other function that adds buttons to a command bar is this one: 


BOOL CommandBar_InsertButton (HWND hwndCB, int iButton, 
LPTBBUTTON IpButton) ; 


This function inserts one button into the command bar to the left of the button refer- 
enced by the iButton parameter. The parameters in this function mimic the param- 
eters in CommandBar_AddButtons with the exception that the JpButton parameter 
points to a single TBBUTTON structure. The iButton parameter specifies the posi- 
tion on the command bar of the new button. 


Working with command bar buttons 

When a user presses a command bar button other than a drop-down button, the 
command bar sends a WM_COMMAND message to the parent window of the com- 
mand bar. So, handling button clicks on the command bar is just like handling menu 
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commands. In fact, since many of the buttons on the command bar have menu com- 
mand equivalents, it’s customary to use the same command IDs for the buttons and 
the like functioning menus, thus removing the need for any special processing for 
the command bar buttons. 

The command bar maintains the checked and unchecked state of check and 
checkgroup buttons. After the buttons have been added to the command bar, their 
states can be queried or set using two messages, TB_ISBUTTONCHECKED and 
TB_CHECKBUTTON. (The TB_ prefix in these messages indicates the close relation- 
ship between the command bar and the toolbar controls.) The TB_ISBUTTON- 
CHECKED message is sent with the ID of the button to be queried passed in the 
wParam parameter this way: 


fChecked = SendMessage (hwndCB, TB_ISBUTTONCHECKED, wID, @); 


where bwndCB is the handle to the command bar containing the button. If the return 
value from the TB_ISBUTTONCHECKED message is nonzero, the button is checked. 
To place a button in the checked state, send a TB_CHECKBUTTON message to the 
command bar, as in 


SendMessage (hwndCB, TB_CHECKBUTTON, wID, TRUE); 
To uncheck a checked button, replace the TRUE value in /Param with FALSE. 


A new look for disabled buttons 

Windows CE allows you to easily modify the way a command bar or toolbar button 
looks when the button is disabled. Command bars and toolbars maintain two image 
lists: the standard image list that I described previously and a disabled image list used 
to store bitmaps that you can employ for disabled buttons. 

To use this new feature, you need to create and load a second image list for 
disabled buttons. The easiest way to do this is to create the image list for the nor- 
mal states of the buttons using the techniques I described when I talked about 
CommandBar_AddBitmap. (Image lists in toolbars are loaded with the message 
TB_LOADIMAGES.) Once that image list complete, simply copy the original image 
list and modify the bitmaps of the images to create disabled counterparts to the origi- 
nal images. Then load the new image list back into the command bar or toolbar. A 
short code fragment that accomplishes this chore is shown below. 


HBITMAP hBmp, hMask; 
HIMAGELIST hilDisabled, hilEnabled; 


// Load the bitmap and mask to be used in the disabled image list. 
hBmp = LoadBitmap (hInst, TEXT ("DisCross")); 
hMask = LoadBitmap (hInst, TEXT ("DisMask"™)); 
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// Get the std image list and copy it. 
hilEnabled = (HIMAGELIST)SendMessage (hwndCB, TB _GETIMAGELIST, 0, Q); 
hilDisabled = ImageList_Duplicate (hilEnabled); 


// Replace one bitmap in the disabled list. 
ImageList_Replace (hilDisabled, VIEW_LIST, hBmp, hMask); 


// Set the disabled image list. 
SendMessage (hwndCB, TB_SETDISABLEDIMAGELIST, @, (LPARAM) hilDisabled); 


The code fragment first loads a bitmap and a mask bitmap that will replace one 
of the images in the disabled image list. You retrieve the current image list by send- 
ing a TB_GETIMAGELIST message to the command bar, and then you duplicate it 
using ImageList_Duplicate. One image in the image list is then replaced by the bitmap 
that was loaded earlier. 

This example replaces only one image, but in a real-world example many im- 
ages might be replaced. If all the images were replaced, it might be easier to build 
the disabled image list from scratch instead of copying the standard image list and 
replacing a few bitmaps in it. Once the new image list is created, you load it into the 
command bar by sending a TB_SETDISABLEDIMAGELIST message. The code that I 
just showed you works just as well for toolbars under Windows CE as it does for 
command bars. 


Drop-down buttons 

The drop-down list button is a more complex animal than the standard button on a 
command bar. The button looks to the user like a button that, when pressed, dis- 
plays a list of items for the user to select from. To the programmer, a drop-down button 
is actually a combination of a button and a menu that is displayed when the user clicks 
on the button. Unfortunately, the command bar does little to support a drop-down 
button except to modify the button appearance to indicate that the button is a drop- 
down button and to send a special notification when the button is clicked by the user. 
It’s up to the application to display the menu. 

The notification of the user clicking a drop-down button is sent to the parent 
window of the command bar by a WM_NOTIFY message with a notification value of 
TBN_DROPDOWN. When the parent window receives the TBN_DROPDOWN noti- 
fication, it must create a pop-up menu immediately below the drop-down button 
identified in the notification. The menu is filled by the parent window with what- 
ever selections are appropriate for the button. When one of the menu items is se- 
lected, the menu will send a WM_COMMAND message indicating the menu item 
picked and the menu will be dismissed. The easiest way to understand how to handle 
a drop-down button notification is to look at the following procedure that handles a 
TBN_ DROPDOWN notification. 
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LRESULT DoNotifyMain (HWND hWnd, UINT wMsg, WPARAM wParam, 
LPARAM 1Param) { 
LPNMHDR pNotifyHeader; 
LPNMTOOLBAR pNotifyToolBar; 
RECT rect; 
TPMPARAMS tpm; 
HMENU hMenu; 


// Get pointer to notify message header. 
pNotifyHeader = (LPNMHDR)1Param; 


if (pNotifyHeader->code == TBN_DROPDOWN) { 


// Get pointer to toolbar notify structure. 
pNotifyToolBar = (LPNMTOOLBAR)1 Param; 


// Get the rectangle of the drop-down button. 
SendMessage (pNotifyHeader->hwndFrom, TB_GETRECT, 
pNotifyToolBar->iltem, (LPARAM)&rect); 


// Convert rect into screen coordinates. The rect is 

// considered here to be an array of 2 POINT structures. 

MapWindowPoints (pNotifyHeader->hwndFrom, HWND_DESKTOP, 
(LPPOINT)&rect, 2); 


// Prevent the menu from covering the button. 
tpm.cbSize = sizeof (tpm); 
CopyRect (&tpm.rcExclude, &rect); 


// Load the menu resource to display under the button. 
hMenu = GetSubMenu (LoadMenu (hInst, TEXT ("popmenu"™)),@); 


// Display the menu. This function returns after the 
// user makes a selection or dismisses the menu. 
TrackPopupMenuEx (hMenu, TPM_LEFTALIGN | TPM_VERTICAL, 
rect.left, rect.bottom, hWnd, &tpm); 
i; 


return Q; 


} 


After the code determines that the message is a TBN_DROPDOWN notification, the 
first task of the notification handler code is to get the rectangle of the drop-down 
button. The rectangle is queried so that the drop-down menu can be positioned im- 
mediately below the button. To do this, the routine sends a TB_GETRECT message 
to the command bar with the ID of the drop-down button passed in wParam and a 
pointer to a rectangle structure in /Param. 
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Since the rectangle returned is in the coordinate base of the parent window, 
and pop-up menus are positioned in screen coordinates, the coordinates must be con- 
verted from one basis to the other. You accomplish this using the function 


MapWindowPoints (HWND hwndFrom, HWND hwndTo, 
LPPOINT Ippoints, UINT cPoints); 


The first parameter is the handle of the window in which the coordinates are origi- 
nally based. The second parameter is the handle of the window to which you want 
to map the coordinates. The third parameter is a pointer to an array of points to be 
translated; the last parameter is the number of points in the array. In the routine I just 
showed you, the window handles are the command bar handle and the desktop 
window handle, respectively. 

Once the rectangle has been translated into desktop coordinates, the pop-up, 
or context, menu can be created. You do this by first loading the menu from the re- 
source, then displaying the menu with a call to TrackPopupMenuEx. That function is 
prototyped as 


BOOL TrackPopupMenuEx (HMENU hmenu, UINT fuFlags, int x, int y, 
HWND hwnd, LPTPMPARAMS lptpm); 


The bMenu parameter is the handle of the menu to be displayed. The hwnd param- 
eter identifies the window to receive the WM_COMMAND message if a menu item is 
selected. The TPMPARAMS structure contains a rectangle that won’t be covered up 
by the menu when it is displayed. For our purposes, this rectangle is set to the di- 
mensions of the drop-down button so that the button won’t be covered by the pop- 
up menu. The /uFlags field can contain a number of values that define the placement 
of the menu. For drop-down buttons, the only flag needed is TPM_VERTICAL. If 
TMP_VERTICAL is set, the menu leaves uncovered as much of the horizontal area of 
the exclude rectangle as possible. The TrackPopupMenuEx function doesn’t return 
until an item on the menu has been selected or the menu has been dismissed by the 
user tapping on another part of the screen. 


Combo boxes on the command bar 
Combo boxes on a command bar are much easier to implement than drop-down 
buttons. You add a combo box by calling 


HWND CommandBar_InsertComboBox (HWND hwndCB, HINSTANCE hInst, 
int iWidth, UINT dwStyle, 
WORD idComboBox, 
int iButton); 


This function inserts a combo box on the command bar to the left of the button indi- 
cated by the iButton parameter. The width of the combo box is specified, in pixels, 
by the iWidth parameter. The dwStyle parameter specifies the style of the combo box. 
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The allowable style flags are any valid Windows CE combo box style and window 
styles. The function automatically adds the WS_CHILD and WS_VISIBLE flags when 
creating the combo box. The idComboBox parameter is the ID for the combo box that 
will be used when WM_COMMAND messages are sent notifying the parent window 
of a combo box event. Experienced Windows programmers will be happy to know 
that CommandBar_InsertComboBox takes care of all the “parenting” problems that 
occur when a control is added to a standard Windows toolbar. That one function call 
is all that is needed to create a properly functioning combo box on the command bar. 

Once a combo box is created, you program it on the command bar the same 
way you would a stand-alone combo box. Since the combo box is a child of the com- 
mand bar, you must query the window handle of the combo box by passing the handle 
of the command bar to GetDiglitem with the ID value of the combo box, as in the 
following code: 


hwndCombobox = GetDigItem (GetDigItem (hWnd, IDC_CMDBAR), 
IDC_COMBO) ); 


However, the WM_COMMAND messages from the combo box are sent directly to the 
parent of the command bar, so handling combo box events is identical to handling 
them from a combo box created as a child of the application’s top-level window. 


Command bar tool tips 
Tool tips are small windows that display descriptive text that labels a command bar 
button when the stylus is held down over the control. Tool tips under Windows CE 
are implemented in a completely different way from how they’re implemented under 
Windows 98 and Windows NT. 

You add tool tips to a command bar by using this function: 


BOOL CommandBar_AddToolTips (HWND hwndCB, UINT uNumToolTips, 
LPTSTR IpToolTips); 


The /pToolTips parameter must point to an array of pointers to strings. The wNumTool- 
Tips parameter should be set to the number of elements in the string pointer array. 
The CommandBar_AddToolTips function doesn’t copy the strings into its own storage. 
Instead, the location of the string array is saved. This means that the block of memory 
containing the string array must not be released until the command bar is destroyed. 

Each string in the array becomes the tool tip text for a control or separator on 
the command bar excluding the menu. The first string in the array becomes the tool 
tip for the first control or separator, the second string is assigned to the second con- 
trol or separator, and so on. So, even though combo boxes and separators don’t dis- 
play tool tips, they must have entries in the string array so that all the text lines up 
with the proper buttons. 
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Other command bar functions 

A number of other functions assist in command bar management. The CommandBar_ 
Height function returns the height of the command bar and is used in all the example 
programs that use the command bar. Likewise, the CommandBar_AddAdornments 
function is also used whenever a command bar is used. This function, prototyped as 


BOOL CommandBar_AddAdornments (HWND hwndCB, DWORD dwFlags, 
DWORD dwReserved); 


places a Close button and, if you want, a Help button and an OK button on the ex- 
treme right of the command bar. You pass a CMDBAR_HELP flag to the dwFlags pa- 
rameter to add a Help button, and you pass a CMDBAR_OK flag to add an OK button. 

The Help button is treated differently from other buttons on the command bar. 
When the Help button is pressed, the command bar sends a WM_HELP message to 
the owner of the command bar instead of the standard WM_COMMAND message. 
The OK button’s action is more traditional. When it is pressed, a WM_COMMAND 
message is sent with a control ID of IDOK. CommandBar_AddAdornments must be 
called after all other conrols of the command bar have been added. 

A command bar can be hidden by calling 


BOOL CommandBar_Show (CHWND hwndCB, BOOL fShow); 


The /Show parameter is set to TRUE to show the command bar and FALSE to hide a 
command bar. The visibility of a command bar can be queried with this: 


BOOL CommandBar_IsVisible (HWND hwndCB); 
Finally, a command bar can be destroyed using this: 
void CommandBar_Destroy (HWND hwndCB); 


Although a command bar is automatically destroyed when its parent window is 
destroyed, sometimes it’s more convenient to destroy a command bar manually. This 
is often done if a new command bar is needed for a different mode of the applica- 
tion. Of course, you can create multiple command bars, hiding all but one and switch- 
ing between them by showing only one at a time, but this isn’t good programming 
practice under Windows CE because all those hidden command bars take up valu- 
able RAM that could be used elsewhere. The proper method is to destroy and create 
command bars on the fly. You can create a command bar fast enough so that a user 
shouldn’t notice any delay in the application when a new command bar is created. 


Design guidelines for command bars 

Because command bars are a major element of Windows CE applications, it’s not 
surprising that Microsoft has a rather strong set of rules for their use. Many of these 
rules are similar to the design guidelines for other versions of Windows, such as the 
recommendations for the ordering of main menu items and the use of tool tips. Most 
of these guidelines are already second nature for Windows programmers. 
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Figure 5-4. The CmdBar program. 


280 


Chapter 5 Common Controls and Windows CE 


(continued) 


281 


igure 5-4. continued 


F 


282 


Chapter 5 Common Controls and Windows CE 


(continued) 


283 


Figure 5-4. continued 


284 


Chapter 5 Common Controls and Windows CE 


(continued) 


285 


nued 


conti 


4 


5 


F 


igure 


foooadth 


286 


Chapter 5 Common Controls and Windows CE 


(continued) 


287 


Figure 5-4. continued 


288 


Chapter 5 Common Controls and Windows CE 


(continued) 


289 


iS 


d 


igure 5-4. continue 


F 


290 


Chapter 5 Common Controls and Windows CE 


(continued) 


291 


d 


continue 


-4 


Figure 5 


Chapter 5 Common Controls and Windows CE 


(continued) 


293 


Part Il 


Figure 5-4. continued 


Each of the three command bars created in CmdBar demonstrate different ca- 
pabilities of the command bar control. The first command bar, created in the routine 
DoMainCommandVStd creates a vanilla command bar with a menu and a set of but- 
tons. The button structure for this command bar is defined in the array toCBStdBins, 
which is defined near the top of CmdBar.C. 

The second command bar, created in the routine DoMainCommandVView, 
contains two groups of checkgroup buttons separated by a combo box. This com- 
mand bar also demonstrates the use of a separate image for a disabled button. The 
list view button, the third button on the bar, is disabled. The image for that button in 
the image list for disabled buttons is replaced with a bitmap that looks like an X. 

The DoMainCommandVCombo routine creates the third command bar. It uses 
both the standard and view bitmap images as well as a custom bitmap for a drop- 
down button. This command bar demonstrates the technique of referencing the im- 
ages in an image list that contains multiple bitmaps. The drop-down button is serviced 
by the OnNotifiyMain routine where a pop-up menu is loaded and displayed when 
a TBN_DROPDOWN notification is received. 
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Command bands appeared in Windows CE 2.0 and are a valuable feature, especially 
in their capacity to contain separate bands that can be dragged around by a user. Each 
individual band can have a “gripper” that can be used to drag the band to a new 
position. A band can be in a minimized state, showing only its gripper and, if you 
want, an icon; in a maximized state, covering up the other bands on the line; or re- 
stored, sharing space with the other bands on the same line. You can even move bands 
to a new row, creating a multiple-row command band. 


Chapter 5 Common Controls and Windows CE 


The standard use of a command bands control is to break up the elements of a 
command bar—menu, buttons, and other controls—into separate bands. This allows 
users to rearrange these elements as they see fit. Users can also expose or overlap 
separate bands as needed in order to provide a larger total area for menus, buttons, 
and other controls. 


Creating a command bands control 
Creating a command bands control is straightforward, if a bit more involved than 
creating a command bar control. You create the control by calling 


HWND CommandBands_Create (HINSTANCE hinst, HWND hwndParent, UINT wID, 
DWORD dwStyles, HIMAGELIST himl); 
The dwStyles parameter accepts a number of flags that define the look and operation 


of the command bands control. These styles match the rebar styles; the command 
bands control is, after all, closely related to the rebar control. 


M RBS_AUTOSIZE Bands are automatically reformatted if the size or posi- 
tion of the control is changed. 


M RBS_BANDBORDERS Each band is drawn with lines to separate adjacent 
bands. 


M RBS_FIXEDORDER Bands can be moved but always remain in the same 
order. 


M RBS_SMARTLABELS When minimized, a band is displayed with its icon. 
When restored or maximized, the band’s label text is displayed. 


M RBS_VARHEIGHT Each row in the control is vertically sized to the mini- 
mum required by the bands on that row. Without this flag, the height of 
every row is defined by the height of the tallest band in the control. 


| CCS_VERT Creates a vertical command bands control. 


M RBS_VERTICALGRIPPER Displays a gripper appropriate for a vertical 
command bar. This flag is ignored unless CCS_VERT is set. 


Of these styles, the RBS_SMARTLABLES and RBS_VARHEIGHT are the two most 
frequently used flags. The RBS_SMARTLABLES flag lets you choose an attractive ap- 
pearance for the command bands control without requiring any effort from the ap- 
plication. The RBS_VARHEIGHT flag is important if you use controls in a band other 
than the default command bar. The CCS_VERT style creates a vertical command bands 
control, but because Windows CE doesn’t support vertical menus, any band with a 
menu won’t be displayed correctly in a vertical band. As you'll see, however, you 
can hide a particular band when the control is orientated vertically. 
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IMAGE LISTS FOR COMMAND BANDS CONTROLS 


I touched on image lists earlier. Command bars and toolbars use image lists in- 
ternally to manage the images used on buttons. Image lists can be managed in 
a stand-alone image list control. This control is basically a helper control that 
assists applications in managing a series of like-size images. The image list control | 
in Windows CE is identical to the image list control under Windows NT and Win- 
dows 98, with the exception that the Windows CE version can’t contain cursors 
for systems built without mouse/cursor support. For the purposes of the com- 
mand bands control, the image list just needs to be created and a set of bitmaps 
added that will represent the individual bands when they’re minimized. An ex- 
ample of the minimal code required for this is shown here: 


himl = ImageList_Create (16, 16, ILC_COLOR, 2, Q@); 
hBmp = LoadBitmap (hInst, TEXT ("CmdBarBmps") ); 
ImageList_Add (himl, hBmp, NULL); 

DeleteObject (hBmp); 


The ImageList_Create function takes the dimensions of the images to be 
loaded, the format of the images (LC_COLOR is the default), the number of 
images initially in the list, and the number to be added. The two images are 
then added by loading a double-wide bitmap that contains two images and calling 
ImageList_Add. After the bitmap has been loaded into the image list, it should 
be deleted. 


Adding bands 
You can add bands to your application by passing an array of REBARBANDINFO struc- 
tures that describe each band to the control. The function is 


BOOL CommandBands_AddBands (HWND hwndCmdBands, HINSTANCE hinst, 
UINT cBands, LPREBARBANDINFO prbbi):; 


Before you call this function, you must fill out a REBARBANDINFO structure for each 
of the bands to be added to the control. The structure is defined as 


typedef struct tagREBARBANDINFO{ 
UINT cbSize; 
UINT fMask; 
UINT fStyle; 
COLORREF clrFore; 
COLORREF clrBack; 
LPTSTR IpText; 
UINT cch; 
int ilmage; 
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HWND hwndChild; 
UINT cxMinChild; 
UINT cyMinChild; 
UINT cx; 
HBITMAP hbmBack; 
UINT wID; 
UINT cyChild; 
UINT cyMaxChild; 
UINT cyIntegral; 
UINT cxIdeal; 
LPARAM 1Param; 

} REBARBANDINFO; 


Fortunately, although this structure looks imposing, many of the fields can be ignored 
because there are default actions for uninitialized fields. As usual with a Windows 
structure, the cbSize field must be filled with the size of the structure as a fail-safe 
measure when the structure is passed to Windows. The /Mask field is filled with a 
number of flags that indicate which of the remaining fields in the structure are filled 
with valid information. I’ll describe the flags as I cover each of the fields. 

The /Style field must be filled with the style flags for the band if the RBBIM_STYLE 
flag is set in the fMask field. The allowable flags are the following: 


M jRBBS_BREAK The band will start on a new line. 


M RBBS_FIXEDSIZE The band can’t be sized. When this flag is specified, 
the gripper for the band isn’t displayed. 


M RBBS_HIDDEN The band won’t be visible when the command band is 
created. 


M RBBS_GRIPPERALWAYS The band will have a sizing grip, even if it’s the 
only band in the command band. 


M RBBS_NOGRIPPER The band won’t have a sizing grip. The band there- 
fore can’t be moved by the user. 


M RBBS_NOVERT The band won’t be displayed if the command bands 
control is displayed vertically due to the CCS_VERT style. 


M $RBBS_CHILDEDGE The band will be drawn with an edge at the top and 
bottom of the band. 


M RBBS_FIXEDBMP The background bitmap of the band doesn’t move 
when the band is resized. 


For the most part, these flags are self-explanatory. Although command bands 
are usually displayed across the top of a window, they can be created as vertical bands 
and displayed down the left side of a window. In that case, the RBBS_NOVERT style 
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allows the programmer to specify which bands won’t be displayed when the com- 
mand band is in a vertical orientation. Bands containing menus or wide controls are 
candidates for this flag because they won’t be displayed correctly on vertical bands. 

You can fill the clrFore and clrBack fields with a color that the command band 
will use for the foreground and background color when your application draws the 
band. These fields are used only if the RBBIM_COLORS flag is set in the mask field. 
These fields, along with the bbmBack field, which specifies a background bitmap for 
the band, are useful only if the band contains a transparent command bar. Otherwise, 
the command bar covers most of the area of the band, obscuring any background 
bitmap or special colors. Pll explain how to make a command bar transparent in the 
section, “Configuring individual bands.” 

The /pText field specifies the optional text that labels the individual band. This 
text is displayed at the left end of the bar immediately right of the gripper. The iJmage 
field is used to specify a bitmap that will also be displayed on the left end of the bar. 
The ilmage field is filled with an index to the list of images contained in the image 
list control. The text and bitmap fields take added significance when paired with the 
RBS_SMARTLABELS style of the command band control. When that style is specified, 
the text is displayed when the band is restored or maximized and the bitmap is dis- 
played when the band is minimized. This technique is used by the H/PC Explorer on 
its command band control. 

The wilD field should be set to an ID value that you use to identify the band. 
The band ID is important if you plan on configuring the bands after they have been 
created or if you think you’ll be querying their state. Even if you don’t plan to use 
band IDs in your program, it’s important that each band ID be unique because the 
control itself uses the IDs to manage the bands. This field is checked only if the 
RBBIM_ID flag is set in the fMask field. 

The hwndChild field is used if the default command bar control in a band is 
replaced by another control. To replace the command bar control, the new control 
must first be created and the window handle of the control then placed in the 
hwndcChild field. The hwndChild field is checked only if the RBBIM_CHILD flag is set 
in the fMask field. 

The cxMinChild and cyMinChild fields define the minimum dimensions to which 
a band can shrink. When you're using a control other than the default command bar, these 
fields are useful for defining the height and minimum width (the width when minimized) 
of the band. These two fields are checked only if the RBBIM_CHILDSIZE flag is set. 

The cxIdeal field is used when a band is maximized by the user. If this field 
isn’t initialized, a maximized command band stretches across the entire width of the 
control. By setting cx/deal, the application can limit the maximized width of a band, 
which is handy if the controls on the band take up only part of the total width of the 
control. This field is checked only if the RBBIM_IDEALSIZE flag is set in the (Mask field. 

The /Param field gives you a space to store an application-defined value with 
the band information. This field is checked only if the RBBIM_LPARAM flag is set in 
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the {Mask field. The other fields in the REBARBANDINFO apply to the more flexible 
rebar control, not the command band control. The code below creates a command 
bands control, initializes an array of three REBARBANDINFO structures, and adds the 
bands to the control. 


// Create a command bands ctl. 
hwndCB = CommandBands_Create (hInst, hWnd, IDC_CMDBAND, RBS_SMARTLABELS | 
RBS_VARHEIGHT, himl); 


// Init common REBARBANDINFO structure fields. 
for (i = @; i < dim(rbi); i++) { 
rbiLi].cbSize = sizeof (REBARBANDINFO); 
rbilil].fMask = RBBIM_ID | RBBIM_IMAGE | RBBIM_SIZE | RBBIM_STYLE; 
rbiLlil.fStyle = RBBS_FIXEDBMP; 
rbifi].wID = IDB_CMDBAND+i ; 
} 
// Init REBARBANDINFO structure for each band. 
// 1. Menu band. 
rbil@].fStyle |= RBBS_NOGRIPPER; 
rbiL@].cx = 130; 
rbiLQ@].iImage = @Q@; 


// 2. Standard button band. 
rbif1].fMask |= RBBIM_TEXT; 
rbiLlj].cx = 200; 

rbillj].iImage = 1; 

rbifl].lpText = TEXT ("Std Btns"); 


I] 


// 3. Edit control band. 

hwndChild = CreateWindow (TEXT ("edit"), TEXT ("edit ctl"), 
WS_VISIBLE | WS_CHILD | WS_BORDER, 
0, 0, 10, 5, hWnd, (HMENU)IDC_EDITCTL, 
hInst, NULL); 


rbil2].fMask |= RBBIM_TEXT | RBBIM_STYLE | RBBIM_CHILDSIZE | RBBIM_CHILD; 
rbil[2].fStyle |= RBBS_CHILDEDGE; 

rbif2].hwndChild = hwndChild; 

rbil2].cxMinChild Q; 

rbiL[2].cyMinChild = 25; 

rbi[2].cyChild = 55; 

rbi[2].cx = 130; 

rbiL2].iImage = 2; 

rbil2].]pText = TEXT ("Edit field"); 


// Add bands. 
CommandBands_AddBands (hwndCB, hInst, 3, rbi); 
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The command bands control created above has three bands, one contain- 
ing a menu, One containing a set of buttons, and one containing an edit control 
instead of a command bar. The control is created with the RBS_SMARTLABELS 
and RBS_VARHEIGHT styles. The smart labels display an icon when the bar is mini- 
mized and a text label when the band isn’t minimized. The RBS_VARHEIGHT style 
allows each line on the control to have a different height. 

The common fields of the REBARBANDINFO structures are then initialized in a 
loop. Then the remaining fields of the structures are customized for each band on 
the control. The third band, containing the edit control, is the most complex to ini- 
tialize. This band needs more initialization since the edit control needs to be prop- 
erly sized to match the standard height of the command bar controls in the other bands. 

The ilmage field for each band is initialized using an index into an image list that 
was created and passed to the CommandBands_Create function. The text fields for 
the second and third bands are filled with labels for those bands. The first band, which 
contains a menu, doesn’t contain a text label because there’s no need to label the menu. 
You also use the RBBS_NOGRIPPER style for the first band so that it can’t be moved 
around the control. This fixes the menu band at its proper place in the control. 

Now that we’ve created the bands, it’s time to see how to initialize them. 


Configuring individual bands 
At this point in the process, the command bands control has been created and the 
individual bands have been added to the control. We have one more task, which is 
to configure the individual command bar controls in each band. (Actually, there’s little 
more to configuring the command bar controls than what I’ve already described for 
command bars.) 

The handle to a command bar contained in a band is retrieved using 


HWND CommandBands_GetCommandBar (HWND hwndCmdBands, UINT uBand); 


The uBand parameter is the zero-based band index for the band containing the com- 
mand bar. If you call this function when the command bands control is being initial- 
ized, the index value correlates directly with the order in which the bands were added 
to the control. However, once the user has a chance to drag the bands into a new 
order, your application must obtain this index indirectly by sending a RB_IDTOINDEX 
message to the command bands control, as in 


nIndex = SendMessage (hwndCmdBands, RB_IDTOINDEX, ID_BAND, 90); 


This message is critical for managing the bands because many of the functions and 
messages for the control require the band index as the method to identify the band. 
The problem is that the index values are fluid. As the user moves the bands around, 
these index values change. You can’t even count on the index values being consecu- 
tive. So, as a rule, never blindly use the index value without first querying the proper 
value by translating an ID value to an index value with RB_IDTOINDEX. 
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Once you have the window handle to the command bar, simply add the menu 
or buttons to the bar using the standard command bar control functions and mes- 
sages. Most of the time, you’ll specify only a menu in the first bar, only buttons in the 
second bar, and other controls in the third and subsequent bars. 

The following code completes the creation process shown in the earlier code 
fragments. This code initializes the command bar controls in the first two bands. Since 
the third band has an edit control, you don’t need to initialize that band. The final act 
necessary to complete the command band control initialization is to add the close 
box to the control using a call to CommandBands_AddAdornments. 


// Add menu to first band. 
hwndBand = CommandBands_GetCommandBar (hwndCB, Q); 
CommandBar_InsertMenubar (hwndBand, hInst, ID_MENU, Q); 


// Add std buttons to second band. 

hwndBand = CommandBands_GetCommandBar (hwndCB, 1); 

CommandBar_AddBitmap (hwndBand, HINST_COMMCTRL, IDB_STD_SMALL_COLOR, 
15, 0, Q@); 

CommandBar_AddButtons (hwndBand, dim(tbCBStdBtns), tbCBStdBtns); 


// Add exit button to command band. 
CommandBands_AddAdornments (hwndCB, hInst, @, NULL); 


Saving the band layout 
The configurability of the command bands control presents a problem to the pro- 
grammer. Users who rearrange the bands expect their customized layout to be re- 
stored the next time the application is started. This task is supposed to be made easy 
using the following function. 


BOOL CommandBands_GetRestoreInformation (HWND hwndCmdBands, 
UINT uBand, LPCOMMANDBANDSRESTOREINFO pcbr); 


This function saves the positioning information from an individual band into a 
COMMANDBANDSRESTOREINFO structure. The function takes the handle of the 
command bands control and an index value for the band to be queried. The follow- 
ing code fragment shows how to query the information from each of the bands in a 
command band control. 


// Get the handle of the command bands control. 
hwndCB = GetDlgItem (hWnd, IDC_CMDBAND) ; 


// Get information for each band. 


for (i = @; i < NUMBANDS; i++) { 
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// Get band index from ID value. 
nBand = SendMessage (hwndCB, RB_IDTOINDEX, IDB_CMDBAND+i, Q); 


// Initialize the size field and get the restore information. 
cbr[Li].cbSize = sizeof (COMMANDBANDSRESTOREINFO) ; 
CommandBands_GetRestoreInformation (hwndCB, nBand, &cbr[i]): 


The code above uses the RB_IDTOINDEX message to convert known band IDs 
into the unknown band indexes required by CommandBands_GetkestoreInformation. 
The data from the structure would normally be stored in the system registry. I’ll talk 
about how to read and write registry data in Chapter 7, “Files, Databases, and the 
Registry.” 

The restore information should be read from the registry when the application 
is restarted, and used when creating the command bands control. 


// Restore configuration to a command band. 
COMMANDBANDSRESTOREINFO cbr[NUMBANDS]; 
REBARBANDINFO rbi: 


// Initialize size field. 
rbi.cbSize = sizeof (REBARBANDINFO); 


// Set only style and size fields. 
rbi.fMask = RBBIM_STYLE | RBBIM_SIZE; 


// Set the size and style for all bands. 
for (i = 0; i < NUMBANDS; i++) { 
rbi.cx = cbr[i].cxRestored; 
rbi.fStyle = cbr[i].fStyle; 


nBand = SendMessage (hwndCB, RB_IDTOINDEX, cbr[i].wID, 0); 
SendMessage (hwndCB, RB_SETBANDINFO, nBand, (LPARAM) &rbi); 
} 


// Only after the size is set for all bands can the bands 
// needing maximizing be maximized. 
for (i = 0; i < NUMBANDS; i++) { 
if (cbrlLi].fMaximized) { 
nBand = SendMessage (hwndCB, RB_IDTOINDEX, cbr[Li].wID, Q); 
SendMessage (hwndCB, RB_MAXIMIZEBAND, nBand, TRUE); 


This code assumes that the command bands control has already been created 
in its default configuration. In a real-world application, the restore information for 
the size and style could be used when first creating the control. In that case, all that 
would remain would be to maximize the bands depending on the state of the 
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[Maximized field in the COMMANDBANDSRESTOREINFO structure. This last step must 
take place only after all bands have been created and properly resized. 

One limitation of this system of saving and restoring the band layout is that you 
have no method for determining the order of the bands in the control. The band in- 
dex isn’t likely to provide reliable clues because after the user has rearranged the bands 
a few times, the indexes are neither consecutive nor in any defined order. The only 
way around this problem is to constrain the arrangement of the bands so that the user 
can’t reorder the bands. You do this by setting the RBS_FIXEDORDER style. This solves 
your problem, but doesn’t help users if they want a different order. In the example 
program at the end of this section, I use the band index value to guess at the order. 
But this method isn’t guaranteed to work. 


Handling command band messages 

The command bands control needs a bit more maintenance than a command bar. 
The difference is that the control can change height, and thus the window contain- 
ing the command bands control must monitor the control and redraw and perhaps 
reformat its client area when the control is resized. 

The command bands control sends a number of different WM_NOTIFY 
messages when the user rearranges the control. To monitor the height of the 
control, your application needs to check for a RBN_HEIGHTCHANGE notifica- 
tion and to react accordingly. The code below does just this: 


// This code is inside a WM_NOTIFY message handler. 
LPNMHDR pnmh; 


pnmh = (LPNMHDR)1Param; 

if (pnmh->code == RBN_HEIGHTCHANGE) { 
InvalidateRect (hWnd, NULL, TRUE); 

j 


If a RBN_HEIGHTCHANGE notification is detected, the routine simply invali- 
dates the client area of the window forcing a WM_PAINT message. The code in the 
paint message then calls 


UINT CommandBands_Height (HWND hwndCmdBands); 


to query the height of the command bands control and subtracts this height from the 
client area rectangle. 

As with the command bar, the command bands control can be hidden and shown 
with a helper function: 


BOOL CommandBands_Show (HWND hwndCmdBands, BOOL fShow); 
The visibility state of the control can be queried using 


BOOL CommandBands_IsVisible (HWND hwndCmdBands); 
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The CmdBand Example Program 


The CmdBand program demonstrates a fairly complete command bands control. The 
example creates three bands: a fixed menu band, a band containing a number of 
buttons, and a band containing an edit control. Transparent command bars and a 
background bitmap in each band are used to create a command bands control with 
a background image. 

You can use the View menu to replace the command bands control with a simple 
command bar by choosing Command Bar from the View menu. You can then recre- 
ate and restore the command bands control to its last configuration by choosing 


Command Bands from the View menu. The code for the CmdBand program is shown 
in Figure 5-5 . 


Figure 5-5. The CmdBand program. 


304 


Chapter 5 Gommon Controls and Windows CE 


(continued) 
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Figure 5-5. continued 
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Figure 5-5. continued 
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Figure 5-5. continued 
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Figure 5-5. continued 
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Figure 5-5. continued 
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CmdBand creates the command band in the CreateCommandBand routine. 


This routine is initially called in OnCreateMain and later in the DoMainCommand- 
VCmdBand menu handler. The program creates the command bands control using 
the RBS_SMARTLABELS style along with an image list and text labels to identify each 
band when it’s minimized and when it’s restored or maximized. An image list is cre- 
ated and initialized with the bitmaps that are used when the bands are minimized. 

The array of REBARBANDINFO structures is initialized to define each of 
the three bands. If the control had previously been destroyed, data from the 
COMMANDBANDSRESTOREINFO structure is used to initialize the style and cx fields. 
The CreateCommandBand routine also makes a guess at the order of the button 
and edit bands by looking at the band indexes saved when the control was last de- 
stroyed. While this method isn’t completely reliable for determining the previous 
order of the bands, it gives you a good estimate. 

When the command bands control is created, the command bars in each band 
are also modified to set the TBS_TRANSPARENT style. This process, along with a 
background bitmap defined for each band, demonstrates how you can use a back- 
ground bitmap to make the command bands control have just the right look. 

When CmdBand replaces the command bands control with a command bar, the 
application first calls the DestroyCommandBand function to save the current con- 
figuration and then destroy the command bands control. This function uses the 
CommandBands_GetRestoreInformation to query the size and style of each of the 
bands. The function also saves the band index for each band to supply the data for 
the guess on the current order of the button and edit bands. The first band, the menu 
band, is fixed with the RBBS_NOGRIPPER style, so there’s no issue as to its position. 

This completes the discussion of the command bar and command bands con- 
trols. I talk about these two controls at length because you'll need one or the other 
for almost every Windows CE application. 
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For the remainder of the chapter, P’ll cover the highlights of some of the other 
controls. These other controls aren’t very different from their counterparts under 
Windows 98 and Windows NT. I'll spend more time on the controls I think you'll need 
when writing a Windows CE application. I’ll start with the month calendar and the 
time and date picker controls. These controls are rather new to the common control 
set and have a direct application to the PIM-like applications that are appropriate for 
many Windows CE systems. Ill also spend some time covering the list view control, 
concentrating on features of use to Windows CE developers. The remainder of the 
common controls, I’ll cover just briefly. 


The Month Calendar Control 


The month calendar control gives you a handy month-view calendar that can be 
manipulated by users to look up any month, week, or day as far back as the adop- 
tion of the Gregorian calendar in September 1752. The control can display as many 
months as will fit into the size of the control. The days of the month can be high- 
lighted to indicate appointments. The weeks can indicate the current week into the 
year. Users can spin through the months by tapping on the name of the month or 
change years by tapping on the year displayed. 

Before using the month calendar control, you must initialize the common con- 
trol library either by calling InitCommoncControls or by calling InitCommonControlsEx 
with the ICC_DATE_CLASSES flag. You create the control by calling CreateWindow 
with the MONTHCAL_CLASS flag. The style flags for the control are shown here: 


M MCS_MULTISELECT ‘The control allows multiple selection of days. 


M@ MCS_NOTODAY The control won’t display today’s date under the 
calendar. 


M MCS_NOTODAYCIRCLE The control won't circle today’s date. 


mM MCS_WEEKNUMBERS The control displays the week number (1 through 
52) to the left of each week in the calendar. 


M MCS_DAYSTATE The control sends notification messages to the parent 
requesting the days of the month that should be displayed in bold. You use 
this style to indicate which days have appointments or events scheduled. 


Initializing the control 

In addition to the styles I just described, you can use a number of messages or their 
corresponding wrapper macros to configure the month calendar control. You can use 
an MCM_SETFIRSTDAYOFWEEK message to display a different starting day of the 
week. You can also use the MCM_SETRANGE message to display dates within a given 
range in the control You can configure date selection to allow the user to choose only 
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single dates or to set a limit to the range of dates that a user can select at any one 
time. The single/multiple date selection ability is defined by the MCS_MULTISELECT 
style. If you set this style, you use the MCM_SETMAXSELCOUNT message to set the 
maximum number of days that can be selected at any one time. 

You can set the background and text colors of the control by using the MCM_ 
SETCOLOR message. This message can individually set colors for the different regions 
within the controls, including the calendar text and background, the header text and 
background, and the color of the days that precede and follow the days of the month 
being displayed. This message takes a flag indicating what part of the control to set 
and a COLORREF value to specify the color. 

The month calendar control is designed to display months on an integral basis. 
That is, if the control is big enough for one and a half months, it displays only one 
month, centered in the control. You can use the MCM_GETMINREQRECT message 
to compute the minimum size necessary to display one month. Because the control 
must first be created before the MCM_GETMINREQRECT can be sent, properly siz- 
ing the control is a round-about process. You must create the control, send the 
MCM_GETMINREQRECT message, and then resize the control using the data returned 
from the message. 


Month calendar notifications 
The month calendar control has only three notification messages to send to its par- 
ent. Of these, the MCN_GETDAYSTATE notification is the most important. This noti- 
fication is sent when the control needs to know what days of a month to display in 
bold. This is done by querying the parent for a series of bit field values encoded ina 
MONTHDAYSTATE variable. This value is nothing more than a 32-bit value with bits 
1 through 31 representing the days 1 through 31 of the month. 

When the control needs to display a month, it sends a MCN_GETDAYSTATE 
notification with a pointer to an NMDAYSTATE structure defined as the following: 


typedef struct { 
NMHDR nmhdr; 
SYSTEMTIME stStart; 
int cDayState; 
LPMONTHDAYSTATE prgDayState; 
} NMDAYSTATE; 


The nmbhdr field is simply the NMHDR structure that’s passed with every WM_NOTIFY 
message. The stStart field contains the starting date for which the control is request- 
ing information. This date is encoded in a standard SYSTEMTIME structure used by 
all versions of Windows. It’s detailed on the facing page. 
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typedef struct { 

WORD wYear; 

WORD wMonth; 

WORD wDayOfWeek; 

WORD wDay; 

WORD wHour; 

WORD wMinute; 

WORD wSecond; 

WORD wMilliseconds; 
} SYSTEMTIME; 


For this notification, only the wMonth, wDay, and wYear fields are significant. 

The cDayState field contains the number of entries in an array of MONTHDAY- 
STATE values. Even if a month calendar control is displaying only one month, it could 
request information about the previous and following months if days of those months 
are needed to fill in the top or bottom lines of the calendar. 

The month calendar control sends an MCN_SELCHANGE notification when the 
user changes the days that are selected in the control. The structure passed with this 
notification, NUSELCHANGE, contains the newly highlighted starting and ending days. 
The MCN_SELECT notification is sent when the user double-taps on a day. The same 
NMSELCHANGE structure is passed with this notification to indicate the days that have 
been selected. 


The Date and Time Picker Control 


The date and time picker control looks deceptively simple but is a great tool for any 
application that needs to ask the user to specify a date. Any programmer that has had 
to parse, validate, and translate a string into a valid system date or time will appreci- 
ate this control. 

When used to select a date, the control resembles a combo box, which is an 
edit field with a down arrow button on the right side. Clicking on the arrow, how- 
ever, displays a month calendar control showing the current month. Selecting a day 
in the month dismisses the month calendar control and fills the date and time picker 
control with that date. When you configure it to query for a time, the date and time 
picker control resembles an edit field with a spin button on the right end of the 
control. 

The date and time picker control has three default formats: two for displaying 
the date and one for displaying the time. The control also allows you to provide a 
formatting string so that users can completely customize the fields in the control. The 
control even lets you insert application-defined fields in the control. 


Creating a date and time picker control 
Before you can create the date and time picker control, the common control li- 
brary must be initialized. If InitCommonControlsEx is used, it must be passed a 
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ICC_DATE_CLASSES flag. The control is created by using CreateWindow with a class 
of DATETIMEPICK_CLASS. The control defines the following styles: 


M DTS_LONGDATEFORMAT ‘The control displays a date in long format, as 
in Saturday, September 19, 1998. The actual long date format is defined in 
the system registry. 


M DTS_SHORTDATEFORMAT The control displays a date in short format, 
as in 9/19/98. The actual short date format is defined in the system registry. 


MM DTS_TIMEFORMAT The control displays the time in a format such as 
5:50:28 PM. The actual time format is defined in the system registry. 


| DTS_SHOWNONE The control has a check box to indicate that the date 
is valid. 


M DTS_UPDOWN Anup-down control replaces the drop-down button that 
displays a month calendar control in date view. 


M $DTS_APPCANPARSE Allows the user to directly enter text into the con- 
trol. The control sends a DIN_USERSTRING notification when the user is 
finished. 


The first three styles simply specify a default format string. These formats are 
based on the regional settings in the registry. Since these formats can change if the 
user picks different regional settings in the Control Panel, the date and time picker 
control needs to know when these formats change. The system informs top-level 
windows of these types of changes by sending a WM_SETTINGCHANGE message. 
An application that uses the date and time picker control and uses one of these de- 
fault fonts should forward the WM_SETTINGCHANGE message to the control if one 
is sent. This causes the control to reconfigure the default formats for the new regional 
settings. 

The DTS_APPCANPARSE style enables the user to directly edit the text in the 
control. If this isn’t set, the allowable keys are limited to the cursor keys and the 
numbers. When a field, such as a month, is highlighted in the edit field and the user 
presses the 6 key, the month changes to June. With the DIS_APPCANPARSE style, 
the user can directly type any character into the edit field of the control. When the 
user has finished, the control sends a DIN_USERSTRING notification to the parent 
window so that the text can be verified. 


Customizing the format 

To customize the display format, all you need to do is create a format string and send 
it to the control using a DTIM_SETFORMAT message. The format string can be made 
up of any of the following codes: 
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String Description 

fragment 

"q" One- or two-digit day. 

"dd" Two-digit day. Single digits have a leading zero. 

"ddd" The three-character weekday abbreviation. As in Sun, Mon... 


"dddd" The full weekday name. 


"h" One- or two-digit hour (12-hour format). 

"hh" Two-digit hour (12-hour format) Single digits have a leading zero. 
"HH" One- or two-digit hour (24-hour format). 

"HH" Two-digit hour (24-hour format) Single digits have a leading zero. 
"mn" One- or two-digit minute. 

"mm" Two-digit minute. Single digits have a leading zero. 

"mM" One- or two-digit month. 

"MM" Two-digit month. Single digits have a leading zero. 

"MMM" Three-character month abbreviation. 


"MMMM" Full month name. 


a naa The one-letter AM/PM abbreviation. As in A or P. 

i The two-letter AM/PM abbreviation. As in AM or PM. 

"Xx" Specifies a callback field that must be parsed by the application. 
ys One-digit year. As in 8 for 1998. 

"yy" Two-digit year. As in 98 for 1998. 


yyy" Full four-digit year. As in 1998. 


Literal strings can be included in the format string by enclosing them in single 
quotes. For example, to display the string Today is: Saturday, December 5, 1998 the 
format string would be 


"Today is: ‘dddd*, "MMMM' ‘d', ‘yyy 


The single quotes enclose the strings that aren’t parsed. That includes the Today is: 
as well as all the separator characters, such as spaces and commas. 

The callback field, designated by a series of X characters, provides for the ap- 
plication the greatest degree of flexibility for configuring the display of the date. When 
the control detects an X field in the format string, it sends a series of notification 
messages to its owner asking what to display in that field. A format string can have 
any number of X fields. For example the following string has two X fields. 


"Today 'XX"' is: ' dddd', ‘MMMM’ ‘d', ‘yyy’ and is ‘XXX" birthday’ 


The number of X characters is used by the application only to differentiate the 
application-defined fields; it doesn’t indicate the number of characters that should 
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be displayed in the fields. When the control sends a notification asking for informa- 
tion about an X field, it includes a pointer to the X string so that the application can 
determine which field is being referenced. 

When the date and time picker control needs to display an application-defined 
X field, it sends two notifications: DIN_FORMATQUERY and DTN_FORMAT. The 
DTN_FORMATOQUERY notification is sent to get the maximum size of the text to be 
displayed. The DTN_FORMAT notification is then sent to get the actual text for the 
field. A third notification, DIN_.WMKEYDOWN is sent when the user highlights an 
application-defined field and presses a key. The application is responsible for deter- 
mining which keys are valid and modifying the date if an appropriate key is pressed. 


The List View Control 
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The list view control is arguably the most complex of the common controls. It dis- 
plays a list of items in one of four modes: large icon, small icon, list, and report. The 
Windows CE version of the list view control supports many, but not all, of the valu- 
able new features recently added for Internet Explorer 4.0. Some of these new func- 
tions are a great help in the memory-constrained environment of Windows CE. These 
new features include the ability to manage virtual lists of almost any size, headers 
that can have images and be rearranged using drag and drop, the ability to indent an 
entry, and new styles for report mode. The list view control also supports the new 
custom draw interface, which allows a fairly easy way of changing the appearance of 
the control. 

You register the list view control by calling either InitCommonControls or 
InitCommoncControls using a ICC_LISTVIEW_CLASSES flag. You create the control by 
calling CreateWindow using the class filled with WC_LISTVIEW. Under Windows CE, 
the list view control supports all the styles supported by other versions of Windows, 
including the new LVS_OWNERDATA style that designates the control as a virtual list 
view control. 


New styles in report mode 

In addition to the standard list view styles hats you can use when creating the list view, 
the list view control supports a number of extended styles. This rather unfortunate 
term doesn’t refer to the extended styles field in the CreateWindowsEx func- 
tion. Instead, two messages, LVM_GETEXTENDEDLISTVIEWSTYLE and LVM_ 
SETEXTENDEDLISTVIEWSTYLE, are used to get and set these extended list view styles. 
The extended styles supported by Windows CE are listed below. 


M  LVS_EX_CHECKBOXES The control places check boxes next to each item 


in the control. 


M LVS_EX_HEADERDRAGDROP_ Allows headers to be rearranged by the 
user using drag and drop. 
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M LVS_EX_GRIDLINES The control draws grid lines around the items in 
report mode. 


Mm LVS_EX_SUBITEMIMAGES The control displays images in the subitem 
columns in report mode. 


M LVS_EX_FUILROWSELECT ‘The control highlights the item’s entire row 
in report mode when that item is selected. 


Aside from the LVS_EX_CHECKBOXES extended style, which works in all dis- 
play modes, these new styles all affect the actions of the list view when in report mode. 
The effort here has clearly been to make the list view control an excellent control for 
displaying large lists of data. 

Note that the list view control under Windows CE doesn’t support other extended 
list view styles, such as LVS_EX_JINFOTIP, LVS_EX_ONECLICKACTIVATE, LVS_ 
EX_TWOCLICKACTIVATE, LVS_EX_TRACKSELECT, LVS_EX_ REGIONAL, or LVS_EX_ 
FLATSB, supported in some versions of the common control library. 


Virtual list view 

The virtual list view mode of the list view control is a huge help for Windows CE 
devices. In this mode, the list view control tracks only the selection and focus state 
of the items. The application maintains all the other data for the items in the control. 
This mode is handy for two reasons. First, virtual list view controls are fast. The ini- 
tialization of the control is almost instantaneous because all that’s required is that you 
set the number of items in the control. The list view control also gives you hints about 
what items it will be looking for in the near term. This allows applications to cache 
necessary data in RAM and leave the remainder of the data in a database or file. Without 
a virtual list view, an application would have to load an entire database or list of items 
in the list view when it’s initialized. With the virtual list view, the application loads 
only what the control requires to display at any one time. 

The second advantage of the virtual list view is RAM savings. Because the vir- 
tual list view control maintains little information on each item, the control doesn’t keep 
a huge data array in RAM to support the data. The application manages what data is 
in RAM with some help from the virtual list view’s cache hint mechanism. 

The virtual list view has some limitations. The LVS_OWNERDATA style that desig- 
nates a virtual list view can’t be set or cleared after the control has been created. Also, 
virtual list views don’t support drag and drop in large icon or small icon mode. A virtual 
list view defaults to LVS_AUTOARRANGE style and the LVM_SETITEMPOSITION message 
isn’t supported. Also, the sort styles LVS_SORTASCENDING and LVS_SORTDESCENDING 
aren’t supported. Even so, the ability to store large lists of items is handy. 

To implement a virtual list view, an application needs to create a list view control 
with an LVS_OWNERDATA style and handle three notifications—LVN_GETDISPINFO, 
LVN_ODCACHEHINT, and LVN_ODFINDITEM. The LVN_GETDISPINFO notification 
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should be familiar to those of you who have programmed list view controls before. It 
has always been sent when the list view control needed information to display an item. 
In the virtual list view, it’s used in a similar manner but the notification is sent to gather 
all the information about every item in the control. 

The virtual list view lets you know what data items it needs using the LVN_ 
ODCACHEHINT notification. This notification passes the starting and ending index 
of items that the control expects to make use of in the near term. An application can 
take its cue from this set of numbers to load a cache of those items so that they can 
be quickly accessed. The hints tend to be requests for the items about to be displayed 
in the control. Because the number of items can change from view to view in the 
control, it’s helpful that the control tracks this instead of having the application guess 
which items are going to be needed. Because the control often also needs informa- 
tion about the first and last pages of items, it also helps to cache them so that the 
frequent requests for those items don’t clear the main cache of items that will be needed 
again soon. 

The final notification necessary to manage a virtual list view is the LVN_ 
ODFINDITEM notification. This is sent by the control when it needs to locate an item 
in response to a key press or in response to an LVM_FINDITEM message. 


The LView Example Program 
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The LView program demonstrates a virtual list view control. The program creates a 
list view control that displays the contents of a fictional database. A picture of the 
LView window is shown in Figure 5-6 while the LView code is shown in Figure 5-7. 
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Figure 5-6. The LView window. 
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Figure 5-7. The LView program. (continued) 
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Figure 5-7. continued 
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(continued) 
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Figure 5-7. continued 
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(continued) 
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Figure 5-7. continued 
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Figure 5-7. continued 
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(continued) 
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Figure 5-7. continued 
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(continued) 
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Figure 5-7. continued 
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Notice that the size for the database is set to 2000 items by default. Even with 
this large number, the performance of the list view control is quite acceptable. Most 
of the brief application startup time is taken up not by initializing the list view con- 
trol, but just by filling in the dummy database. Support for the virtual list view is cen- 
tered on the OnNotifyMain routine. | 
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Data for each item is supplied to the list view control through responses to the 
LVN_GETDISPINFO notification. The flags in the mask field of the LVDISPINFO deter- 


mine exactly what element of the item is being requested. The code that handles the 
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notification simply requests the item data from the cache and fills in the requested fields. 

The cache implemented by LView uses three separate buffers. Two of the buff- 
ers are initialized with the first and last 100 items from the database. The third 100- 
item cache, referred to as the main cache, is loaded using the hints passed by the list 
view control. 

The routine that reads the data from the cache is located in the GetltemData rou- 
tine. That routine uses the index value of the requested item to see whether the data is 
in the top or bottom caches, and if not, whether it’s in the main cache. If the data 
isn’t in one of the caches, a call to GetDatabaseltem is made to read the data directly 
from the dummy database. 

The routine that handles the cache hints from the list view control is LoadMain- 
Cache. This routine is called when the program receives a LVN_ODCACHEHINT 
notification. The routine takes two parameters, the starting and ending values of the 
hint passed by the notification. The routine first checks to see if the range of items in 
the hint lies in the two end caches that store data from the top and bottom of the 
database. If the range does lie in one of the end caches, the hint is ignored and the 
main cache is left unchanged. If the hint range isn’t in either end cache and isn’t al- 
ready in the current main cache, the main cache is flushed to send any updated in- 
formation back into the database. The cache is then loaded with data from the database 
from the range of items indicated by the hint. 

The cache hint notifications sent by the list view control aren’t necessarily in- 
telligent. The control sends a request for a range of one item if that.item is double- 
clicked by the user. The cache management code should always check to see whether 
the requested data is already in the cache before flushing and reloading the cache 
based on a single hint. The cache strategy you use, and the effort you must make to 
optimize it, of course depends on the access speed of the real data. 


OTHER COMMON CONTROLS 
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Windows CE supports a number of other common controls available under Windows 
98 and Windows NT. Most of these controls are supported completely within the limits 
of the capability of Windows CE. For example, while the tab control supports verti- 
cal tabs, Windows CE supports vertical text only on systems that support TrueType 
fonts. For other systems, including the Palm-size PC, the text in the tabs must be 
manually generated by the Windows CE application by rotating bitmap images of each 
letter. Frankly, it’s probably much easier to devise a dialog box that doesn’t need ver- 
tical tabs. Short descriptions of the other supported common controls follow. 


Chapter 5 Common Controls and Windows CE 


The status bar control 
The status bar is carried over unchanged from the desktop versions of Windows. The 
only difference is that under Windows CE, the SBARS_SIZEGRIP style that created a 
gripper area on the right end of the status bar has no meaning because users can’t 
size Windows CE windows. 


The tab control 

The tab control is fully supported, the above-mentioned vertical text limitation not 
withstanding. But because the stylus can’t hover over a tab, the TCS_HOTTRACK style 
that highlighted tabs under the cursor isn’t supported. The TCS_EX_REGISTERDROP 
extended style is also not supported. 


The trackbar control 

The trackbar control gains the capacity for two “buddy” controls that are automati- 
cally updated with the trackbar value. The trackbar also supports the custom draw 
service, providing separate item drawing indications for the channel, the thumb, and 
the tic marks. 


The progress bar control 

The progress bar includes the latest support for vertical progress bars and 32-bit ranges. 
This control also supports the new smooth progression instead of moving the progress 
indicator in discrete chunks. 


The up-down control 
The up-down control under Windows CE only supports edit controls for its buddy 
control. 


The toolbar control 

The Windows CE toolbar supports tooltips differently from the way tool tips are sup- 
ported by the desktop versions of this control. You add toolbar support for tool tips 
in Windows CE the same way you do for the command bar, by passing a pointer to 
a permanently allocated array of strings. The toolbar also supports the transparent 
and flat styles that are supported by the command bar. 


The tree view control 

The tree view control supports two new styles recently added to the tree view com- 
mon control: TVS_CHECKBOXES and TVS_SINGLESEL. The TVS_CHECKBOXES style 
places a check box adjacent to each item in the control. The TVS_SINGLESEL style 
causes a previously expanded item to close up when a new item is selected. The tree 
view control also supports the custom draw service. The tree view control doesn’t 
support the TVS_TRACKSELECT style, which allows you to highlight an item when 
the cursor hovers over it. 
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UNSUPPORTED COMMON CONTROLS 
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Windows CE doesn’t support four common controls seen under other versions of Win- 
dows. The animation control, the drag list control, the hot key control, and, sadly, the 
rich edit control are all unsupported. Animation would be hard to support given the 
slower processors often seen running Windows CE. The hot key control is problematic 
in that keyboard layouts and key labels, standardized on the PC, vary dramatically on 
the different hardware that runs Windows CE. And the drag list control isn’t that big a 
loss, given the improved power of the report style of the list view control. 

The rich edit control is another story. The lack of an edit control that can con- 
tain multiple fonts and paragraph formatting is a noticeable gap in the Windows CE 
shell. Applications needing this functionality are forced to implement independent, 
and mutually incompatible, solutions. Let’s hope the rich edit control is supported 
under future versions of Windows CE. 

Windows CE supports fairly completely the common control library seen un- 
der other versions of Windows. The date and time picker, month calendar, and com- 
mand bar are a great help given the target audience of Windows CE devices. 

I’ve spent a fair amount of time in the past few chapters looking at the build- 
ing blocks of applications. Now it’s time to turn to the operating system itself. Over 
the next three chapters, I'll cover memory management, files and databases, and 
processes and threads. These chapters are aimed at the core of the Windows CE 
Operating system. 


Chapter 6 


Memory 
Management 


If you have an overriding concern when you’re writing a Microsoft Windows CE pro- 
gram, it should be dealing with memory. A Windows CE machine might have only 1 
or 2 MB of RAM. This is a tiny amount compared to that of a standard personal com- 
puter, which can range somewhere between 16 and 64 MB of RAM. In fact, memory 
on a Windows CE machine is so scarce that it’s often necessary to write programs 
that conserve memory even to the point of sacrificing the overall performance of 
the application. 

Fortunately, although the amount of memory is small in a Windows CE system, 
the functions available for managing that memory are fairly complete. Windows CE 
implements almost the full Win32 memory management API available under Microsoft 
Windows NT and Microsoft Windows 98. Windows CE supports virtual memory allo- 
cations, local and separate heaps, and even memory-mapped files. 

Like Windows NT, Windows CE supports a 32-bit flat address space with memory 
protection between applications. But because Windows CE was designed for differ- 
ent environments, its underlying memory architecture is different from that for Win- 
dows NT. These differences can affect how you design a Windows CE application. In 
this chapter, I’ll cover the basic memory architecture of Windows CE. [ll also cover 
the different types of memory allocation available to Windows CE programs and how 
to use each memory type to minimize your application’s memory footprint. 
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MEMORY BASICS 


As with all computers, systems running Windows CE have both ROM (read only 
memory) and RAM (random access memory). Under Windows CE, however, both 


ROM and RAM are used somewhat differently than they are in a standard personal 


computer. 


About RAM 


The RAM in a Windows CE system is divided into two areas: program memory and 
object store. The object store can be considered something like a permanent virtual 
RAM disk. Unlike the old virtual RAM disks on a PC, the object store retains the files 
stored in it even if the system is turned off.! This is the reason Windows CE systems 
such as the Handheld PC and the Palm-size PC each have a battery and a backup 
battery. When the user replaces the main batteries, the backup battery’s job is to pro- 
vide power to the RAM to retain the files in the object store. Even when the user hits 
the reset button, the Windows CE kernel starts up looking for a previously created 
object store in RAM and uses that store if it finds one. 

The other area of the RAM is devoted to the program memory. Program memory 
is used like the RAM in personal computers. It stores the heaps and stacks for the 
applications that are running. The boundary between the object store and the pro- 
gram RAM is movable. The user can move the dividing line between object store and 
program RAM using the System control panel applet. Under low-memory conditions, 
the system will ask the user for permission to take some object store RAM to use as 
program RAM to satisfy an application’s demand for more RAM. 


About ROM 
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In a personal computer, the ROM is used to store the BIOS (basic input output sys- 
tem) and is typically 64-128 KB. In a Windows CE system, the ROM can range from 
4 to 16 MB and stores the entire operating system, as well as the applications that are 
bundled with the system. In this sense, the ROM in a Windows CE system is like a 
small, read-only hard disk. 

In a Windows CE system, ROM-based programs can be designated as Execute 
in Place CXIP). That is, they’re executed directly from the ROM instead of being loaded 
into program RAM and then executed. This is a huge advantage for small systems in 
two ways. The fact that the code is executed directly from ROM means that the pro- 
gram code doesn’t take up valuable program RAM. Also, since the program doesn’t 


1. On mobile systems like the H/PC and the Palm-size PC, the system is never really off. When the 
user presses the Off button, the system enters a very low power suspended state. 
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have to be copied into RAM before it’s launched, it takes less time to start an appli- 
cation. Programs that aren’t in ROM but are contained in the object store or on a 
Flash memory storage card aren’t executed in place; they’re copied into the RAM 
and executed. 


About Virtual Memory 


Windows CE implements a virtual memory management system. In a virtual memory 
system, applications deal with virtual memory, which is a separate, imaginary address 
space that might not relate to the physical memory address space that’s implemented 
by the hardware. The operating system uses the memory management unit of the 
microprocessor to translate virtual addresses to physical addresses in real time. 

The key advantage of a virtual memory system can be seen in the complexity 
of the MS-DOS address space. Once demand for RAM exceeded the 640-KB limit of 
the original PC design, programmers had to deal with schemes such as expanded and 
extended memory to increase the available RAM. OS/2 1.x and Windows 3.0 replaced 
these schemes with a segment-based virtual memory system. Applications using vir- 
tual memory have no idea (nor should they care) where the actual physical memory 
resides, only that the memory is available. In these systems, the virtual memory was 
implemented in segments, resizable blocks of memory that ranged from 16 bytes to 
64 KB in size. The 64-KB limit wasn’t due to the segments themselves, but to the 16- 
bit nature of the Intel 80286 that was the basis for the segmented virtual memory system 
in Windows 3.x and OS/2 1.x. 


Paged memory 

The Intel 80386 supported segments larger than 64 KB, but when Microsoft and IBM 
began the design for OS/2 2.0, they chose to use a different virtual memory system, 
also supported by the 386, known as a paged virtual memory system. In a paged 
memory system, the smallest unit of memory the microprocessor manages is the page. 
For Windows NT and OS/2 2.0, the pages were set to 386’s default page size of 4096 
bytes. When an application accesses a page, the microprocessor translates the virtual 
address of the page to a physical page in ROM or RAM. A page can also be tagged so 
that accessing the page causes an exception. The operating system then determines 
whether the virtual page is valid and, if so, maps a physical page of memory to the 
virtual page. 

Windows CE implements a paged virtual memory management system similar 
to the other Win32 operating systems, Windows NT and Windows 98. Under Win- 
dows CE, a page is either 1024 or 4096 bytes, depending on the microprocessor, with 
the 1-KB page size preferred by the Windows CE architects. This is a change from 
Windows NT, where page sizes are 4096 bytes for Intel microprocessors and 8192 
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bytes for the DEC Alpha. For the CPUs currently supported by Windows CE, the NEC 
4100 series and the Hitachi SH3 use 1024-byte pages and the 486, the Phillips 3910, 
and Power PC 821 use 4096-byte pages. 

Virtual pages can be in one of three states: free, reserved, or commiited. A free 
page is, as it sounds, free and available to be allocated. A reserved page is a page 
that has been reserved so that its virtual address can’t be allocated by the operating 
system or another thread in the process. A reserved page can’t be used elsewhere, 
but it also can’t be used by the application because it isn’t mapped to physical memory. 
To be mapped, a page must be committed. A committed page has been reserved by 
an application and has been directly mapped to a physical address. 

All that I’ve just explained is old hat to experienced Win32 programmers. The 
important thing for the Windows CE programmer is to learn how Windows CE changes 
the equation. While Windows CE implements most of the same memory API set of its 
bigger Win32 cousins, the underlying architecture of Windows CE does impact pro- 
grams. To better understand how the API is affected, it helps to look at how Win- 
dows CE uses memory under the covers. 


The Windows CE Address Space 
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In OS circles, much is made of the extent to which the operating system goes to pro- 
tect one application’s memory from other applications. Microsoft Windows 95 used 
a single address space that provided minimal protection between applications and 
the Windows operating system code. Windows NT, on the other hand, implements 
completely separate address spaces for each Win32 application, although old 16-bit 
applications under Windows NT do share a single address space. 

Windows CE implements a single, 2-GB virtual address space for all applica- 
tions, but the memory space of an application is protected so that it can’t be accessed 
by another application. A diagram of the Windows CE virtual address space is shown 
in Figure 6-1. A little over half of the virtual address space is divided into thirty-three 
32-MB slots. Each slot is assigned to a currently running process, with the lowest slot, 
slot 0, assigned to the active process. As Windows CE switches between processes, it 
remaps the address space to move the old process out of slot 0 and the new process 
into slot 0. This task is quickly accomplished by the OS by manipulating the page 
translation tables of the microprocessor. 

The region of the address space above the 33 slots is reserved for the operating 
system and for mapping memory-mapped files. Like Windows NT, Windows CE also 
reserves the lowest 64-KB block of the address space from access by any process. 
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Address Comments Slot 


7FFF FFFF End of virtual address space 


Used for memory-mapped files 


4200 0000 

4000 0000 Slot 32 
3E00 0000 Slot 31 
3C00 0000 Slot 30 


AN 25 


OA00 0000 Slot 5 

0800 0000 Slot 4 

0600 0000 Slot 3 

0400 0000 Slot 2 

0200 0000 Process 1: Each slot from 1 to 32 contains one process. Slot 1 
When a process is active, it’s also mapped into slot 0. 

0000 0000 Slot for the currently active process. Slot 0 


First 64 KB reserved by the OS. 


Figure 6-1. A diagram of the Windows CE memory map. 
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Querying the system memory 

If an application knows the current memory state of the system, it can better manage 
the available resources. Windows CE implements both the Win32 GetSystemInfo and 
GlobalMemoryStatus functions. The GetSystemInfo function is prototyped below: 


VOID GetSystemInfo (LPSYSTEM_INFO IpSystemInfo); 
It’s passed a pointer to a SYSTEM_INFO structure defined as 


typedef struct { 
WORD wProcessorArchitecture; 
WORD wReserved; 
DWORD dwPageSize; 
LPVOID IpMinimumApplicationAddress; 
LPVOID I pMaximumApplicationAddress; 
DWORD dwActiveProcessorMask; 
DWORD dwNumberOfProcessors; 
DWORD dwProcessorType; 
DWORD dwAllocationGranularity; 
WORD wProcessorLevel; 
WORD wProcessorRevision; 
} SYSTEM_INFO; 


The wProcessorArchitecture field identifies the type of microprocessor in the 
system. The value should be compared to the known constants defined in Winnt.h, 
such as PROCESSOR_ARCHITECTURE_INTEL. Windows CE has extended these con- 
stants to include PROCESSOR_ARCHITECTURE_ARM, PROCESSOR_ARCHITECTURE_ 
SHx and others. Additional processor constants are added as net CPUs are supported 
by any of the Win32 operating systems. Skipping a few fields, the dwProcessorType 
field further narrows the microprocessor from a family to a specific microprocessor. 
Constants for the Hitachi SHx architecture include PROCESSOR_HITACHI_SH3 and 
PROCESSOR_HITACHI_SH4. The last two fields, wProcessorLevel and wProcessor- 
Revision, further refine the CPU type. The wProcessorLevel field is similar to the 
dwProcessorType field in that it defines the specific microprocessor within a family. 
The dwProcessorkevision field tells you the model and the stepping level of the chip. 

The dwPageSize field specifies the page size, in bytes, of the microprocessor. 
Knowing this value comes in handy when you’re dealing directly with the virtual 
memory API, which I talk about shortly. The /pMinimumApplicationAddress and 
IpMaximumApplicationAddress fields specify the minimum and maximum virtual 
address available to the application. The dwActiveProcessorMask and. dwNumberOf- 
Processors fields are used in Windows NT for systems that support more than one 
microprocessor. Since Windows CE supports only one microprocessor, you can ig- 
nore these fields. The dwAllocationGranularity field specifies the boundaries to which 
virtual memory regions are rounded. Like Windows NT, Windows CE rounds virtual 
regions to 64-KB boundaries. 
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A second handy function for determining the system memory state is this: 
void GlobalMemoryStatus(LPMEMORYSTATUS lpmst); 
which returns a MEMORYSTATUS structure defined as 


typedef struct { 
DWORD dwLength; 
DWORD dwMemoryLoad; 
DWORD dwTotalPhys; 
DWORD dwAvailPhys; 
DWORD dwTotalPageFile; 
DWORD dwAvailPageFile; 
DWORD dwlotalVirtual; 
DWORD dwAvailVirtual:; 
} MEMORYSTATUS; 


The dwLength field must be initialized by the application before the call is made 
to GlobalMemoryStatus. The dwMemoryLoad field is of dubious value; it makes avail- 
able a general loading parameter that’s supposed to indicate the current memory use 
in the system. The dwTotalPhys and dwAvailPhys fields indicate how many pages of 
RAM are assigned to the program RAM and how many are available. These values 
don’t include RAM assigned to the object store. 

The dwTotalPageFile and dwAvailPageFile fields are used under Windows NT 
and Windows 98 to indicate the current status of the paging file. Because paging files 
aren’t supported under Windows CE, these fields are always 0. The dwTotalVirtual 
and dwAvailVirtual fields indicate the total and available number of virtual memory 
pages accessible to the application. 

The information returned by GlobalMemoryStatus provides confirmation of the 
memory architecture of Windows CE. Making this call on an HP 360 H/PC with 8 MB 
of RAM returned the following values: | 


dwMemoryLoad Q@x18 (24) 
dwlotalPhys @x@0555400 (5,592,064) 
dwAvailPhys Q@x@0415C00@ (4,283,392) 


dwlotalPageFile Y) 
dwAvailPageFile Q 
dwlotalVirtual 0x02000000 (33,554,432) 
dwAvailVirtual Ox01EFO000 (32,440,320) 


The dwTotalPhys field indicates that of the 8 MB of RAM in the system, I have 
dedicated 5.5 MB to the program RAM, of which 4.2 MB is still free. Note that there’s 
no way for an application, using this call, to know that another 3 MB of RAM has 
been dedicated to the object store. To determine the amount of RAM dedicated to 
the object store, use the function GetStoreInformation. 

The dwTotalPageFile and dwAvailPageFile fields are 0, indicating no support 
for a paging file under Windows CE. The dwTotalVirtual field is interesting because 
it shows the 32-MB limit on virtual memory that Windows CE enforces on an 
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application. Meanwhile, the dwAvailVirtual field indicates that in this application little 
of that 32 MB of virtual memory is being used. 


An Appliication’s Address Space 


Although it’s always interesting to look at the global memory map for an operating 
system, the fact is an application should be interested only in its own memory space, 
not the global address space. Nevertheless, the design of the Windows CE address 
space does have an impact on applications. Under Windows CE, an application is 
limited to the virtual memory space available in its 32-MB slot. While 32 MB might 
seem like a fair amount of space available to an application that might run on a sys- 
tem with only 4 MB of RAM, Win32 application programmers, used to a 2-GB virtual 
address space, need to keep in mind the limited virtual address space available to a 
Windows CE application. 

Figure 6-2 shows the layout of an application’s 32-MB virtual address space. Each 
line of the figure represents a block of virtual memory made up of one or more pages. 
The address of the blocks are offsets into the application’s slot in the system address 
space. The Page status is free, reserved, private, or image. While I’ve just explained 
the terms free and reserved, private and image merit an explanation. Image indicates 
pages that have been committed and mapped to the image of an executable file in 
ROM or RAM. Private simply means the pages have been committed for use by the 
application. The size field indicates the size of the block, which is always a multiple 
of the page size. The access rights field displays the access rights for the block. 

This memory map was captured on a Casio H/PC that has a SH3 processor with 
a 1024-byte page size. The application used in this example was stored in the object 
store and then launched. This allowed Windows CE to demand page only parts of 
the EXE image into RAM, as they’re needed. If the application had been launched 
from an external storage device that didn’t support demand paging, Windows CE would 
have loaded the entire application into memory when it was launched. 


Address Page Status Size Access Rights Comments 
0000 0000 _—Reserved 65,536 EXE image 
0001 0000 Reserved | 4,096 Code 
0001 1000 —° Image 2,048 Execute, Read only Code 
0001 1800 Reserved 1,024 Code 
0001 1COO0 = Image 1,024 Execute, Read only Code 
0001 2000 Reserved 2,048 Code 
0001 2800 Image 8,192 Execute, Read only Code 
0001 4800 Reserved 2,048 Code 
0001 5000 Image (1,024 Execute, Read only Code 


Figure 6-2. Memory map of a Windows CE Application. 


356 


Address 


0001 5400 
0001 8000 
0001 8COO0 
0001 9000 
0001 9400 
0001 9800 
0001 B400 
0001 D000 
0001 D800 
0001 EOOO 


0002 0000 
0002 D400 
0002 FOOO 


0003 0000 
0003 0400 


0009 0000 


01D9 0000 
01D9 0400 
01DC A400 
01DC ACOO 
01DC C800 
01DC E400 


01DD 1800 


01FD 0000 
01FD 0400 
O1FE D800 
0O1FE DCOO 
O1FE FCOO 
O1FF 0000 
O1FF 1400 


Page Status 


Reserved 
Image 
Reserved 
Image 
Reserved 
Image 
Reserved 
Image 
Reserved 


Free 


Reserved 
Private 


Free 


Private 


Reserved 


Free 


Reserved 
Image 
Image 
Reserved 
Image 


Reserved 


Free 


Reserved 
Image 
Image 
Reserved 
Image 
Reserved 


Free 


Size Access Rights 


11,264 
3,072 
1,024 
1,024 
1,024 
7,168 
7,168 
2,048 
2,048 
8,192 


Read only 


Read/Write 


Read/Write 


Read only 


54,272 
7,168 
4,096 


Read/Write 


1,024 
92,192 


Read/Write 


30,408,704 


1,024 
237,568 
2,048 
7,168 
7,168 
13,312 


Read/Write 


Read only 


2,091,008 


1,024 
119,808 
1,024 
8,192 
1,024 
5,120 
60,416 


Read/Write 


Read only 
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Comments 


Read only static data 
Read/Write static data 
Read/Write static data 
Read/Write static data 
Resource data segment 


Resource data segment 


Stack 


Local heap 


Free 


COMMCTRL image 


Execute, Read only 


Free 


COREDLL image 


Execute, Read only 
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~ Notice that the application is mapped as a 64-KB region starting at 0x10000. 
Remember, the lowest 64 KB of the address space for any application is reserved by 
Windows CE. The image of the file contains the code along with the static data seg- 
ments and the resource segments. Although it appears that the program code is bro- 
ken into a number of disjointed pages from 0x10000 to 0x15400, this is actually the 
result of demand paging. What’s happening is that only the pages containing executed 
code are mapped into the address space. The reserved pages within the code seg- 
ment will be mapped into the space only when they’re executed. 

The read-only static data segment is mapped at 0x18000 and takes three pages. 
The read/write static data is mapped from 0x19000 to 0x1B3FF. Like the code, the 
read/write data segment is committed to RAM only as it’s written to by the applica- 
tion. Any static data that was initialized by the loader is already committed, as is the 
static variables written before this capture of the address space was made. The re- 
sources for the application are mapped starting at 0x1D000. The resources are read 
only and are paged into the RAM only as they’re accessed by the application. 

Starting at 0x20000, the application’s stack is mapped. The stack segment is easily 
recognized because the committed pages are at the end of the reserved section, in- 
dicative of a stack that grows from higher addresses down. If this application had 
more than one thread, more than one stack segment would be reserved in the 
application’s address space. 

Following the stack is the local heap. The heap has only a few blocks currently 
allocated, requiring only one page of RAM. The loader reserves another 392,192 bytes, 
or 383 pages, for the heap to grow. The over-30 MB of address space from the end of 
the reserved pages for the local heap to the start of the DLLs mapped into the ad- 
dress space is free to be reserved and, if RAM permits, committed by the application. 

This application accesses two dynamic-link libraries. Coredll.dll is the DLL that 
contains the entry points to the Windows CE operating system. In Windows CE, the 
function entry points are combined into one DLL, unlike in Windows NT or Win- 
dows 98, where the core functions are distributed across Kernel, User, and GDI. The 
other DLL is the common control DLL, commcetrl.dll. As with the executable image, 
these DLLs are mapped into the address space as linear images. However, unlike the 
EXE, these DLLs are in ROM and directly mapped into the virtual address space of 
the application; therefore, they don’t take up any RAM. 


THE DIFFERENT KINDS 
OF MEMORY ALLOCATION 
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A Windows CE application has a number of different methods for allocating memory. 
At the bottom of the memory-management food chain are the Virtualxxx functions 
that directly reserve, commit, and free virtual memory pages. Next comes the heap API. 
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Heaps are regions of reserved memory space managed by the system for the applica- 
tion. Heaps come in two flavors: the default local heap automatically allocated when 
an application is started, and separate heaps that can be manually created by the 
application. After the heap API is static data—data blocks defined by the compiler 
and that are allocated automatically by the loader. Finally, we come to the stack, where 
an application stores variables local to a function. 

The one area of the Win32 memory API that Windows CE doesn’t support is 
the global heap. The global heap API, which includes calls such as GlobalAlloc, 
GlobalFree, and GlobalRealloc, are therefore not present in Windows CE. The global 
heap is really just a holdover from the Win16 days of Windows 3.x. In Win32, the 
global and local heaps are quite similar. One unique use of global memory, allocat- 
ing memory for data in the clipboard, is handled by using the local heap under Win- 
dows CE. 

The key to minimizing memory use in Windows CE is choosing the proper 
memory-allocation strategy that matches the memory-use patterns for a given block 
of memory. I’ll review each of these memory types and then describe strategies for 
minimizing memory use in Windows CE applications. 


Virtual Memory 


Virtual memory is the most basic of the memory types. The system uses calls to the 
virtual memory API to allocate memory for the other types of memory, including heaps 
and stacks. The virtual memory API, including the VirtualAlloc, VirtualFree, and 
VirtualkeSize functions directly manipulate virtual memory pages in the application’s 
virtual memory space. Pages can be reserved, committed to physical memory, and 
freed using these functions. 


Allocating virtual memory 
Allocating and reserving virtual memory is accomplished using this function: 


LPVOID VirtualAlloc (LPVOID 1lpAddress, DWORD dwSize, 
DWORD flAllocationType, 
DWORD f1Protect); 


The first parameter to VirtualAlloc is the virtual address of the region of memory to 
allocate. The lpAddress parameter is used to identify the previously reserved memory 
block when you use VirtualAlloc to commit a block of memory previously reserved. 
If this parameter is NULL, the system determines where to allocate the memory re- 
gion, rounded to a 64-KB boundary. The second parameter is dwSize, the size of the 
region to allocate or reserve. While this parameter is specified in bytes, not pages, 
the system rounds the requested size up to the next page boundary. 
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The flAllocationType parameter specifies the type of allocation. You can specify 
a combination of the following flags: MEM_COMMIT, MEM_AUTO_COMMIT, MEM_ 
RESERVE, and MEM_TOP_DOWN. The MEM_COMMIT flag allocates the memory to 
be used by the program. MEM_RESERVE reserves the virtual address space to be later 
committed. Reserved pages can’t be accessed until another call is made to VirtualAlloc 
specifying the region and using the MEM_COMMIT flag. The third flag, MEM_TOP_ 
DOWN, tells the system to map the memory at the highest permissible virtual address 
for the application. 

The MEM_AUTO_COMM IT flag is unique to Windows CE and is quite handy. 
When this flag is specified the block of memory is reserved immediately, but each 
page in the block will automatically be committed by the system when it’s accessed 
for the first time. This allows you to allocate large blocks of virtual memory without 
burdening the system with the actual RAM allocation until the instant each page is 
first used. The drawback to auto-commit memory is that the physical RAM needed to 
back up a page might not be available when the page is first accessed. In this case, 
the system will generate an exception. 

VirtualAlloc can be used to reserve a large region of memory with subsequent 
calls committing parts of the region or the entire region. Multiple calls to commit the 
same region won't fail. This allows an application to reserve memory and then blindly 
commit a page before it’s written to. While this method isn’t particularly efficient, it 
does free the application from having to check the state of a reserved page to see 
whether it’s already committed before making the call to commit the page. 

The /lProtect parameter specifies the access protection for the region being al- 
located. The different flags available for this parameter are summarized in the fol- 
lowing list. 


M PAGE_READONLY The region can be read. If an application attempts to 
write to the pages in the region, an access violation will occur. 


M jj PAGE_READWRITE ‘The region can be read from or written to by the 
application. 


M PAGE_EXECUTE ‘The region contains code that can be executed by the 
system. Attempts to read from or write to the region will result in an ac- 
cess violation. 


M PAGE_EXECUTE_READ The region can contain executable code and 
applications can also read from the region. 


M PAGE_EXECUTE_READWRITE The region can contain executable code 
and applications can read from and write to the region. 


Chapter 6 Memory Management 


M PAGE_GUARD The first access to this region results in a STATUS_ 
GUARD_PAGE exception. This flag should be combined with the other 
protection flags to indicate the access rights of the region after the first 
access. 


M PAGE_NOACCESS Any access to the region results in an access violation. 


M PAGE_NOCACHE The RAM pages mapped to this region won’t be cached 
by the microprocessor. 


The PAGE_GUARD and PAGE_NOCHACHE flags can be combined with the other 
flags to further define the characteristics of a page. The PAGE_GUARD flag specifies 
a guard page, a page that generates a one-shot exception when it’s first accessed and 
then takes on the access rights that were specified when the page was committed. 
The PAGE_NOCACHE flag prevents the memory that’s mapped to the virtual page 
from being cached by the microprocessor. This flag is handy for device drivers that 
share memory blocks with devices using direct memory access (DMA). 


Regions vs. pages 

Before I go on to talk about the virtual memory API, I need to make a somewhat subtle 
distinction. Virtual memory is reserved in regions that must align on 64-KB bound- 
aries. Pages within a region can then be committed page by page. You can directly 
commit a page or a series of pages without first reserving a region of pages, but the 
page, or series of pages, directly committed will be aligned on a 64-KB boundary. 
For this reason, it’s best to reserve blocks of virtual memory in 64-KB chunks and 
then commit that page within the region as needed. 

With the limit of a 32-MB virtual memory space per process, this leaves a maxi- 
mum of 32 MB / 64 KB — 1= 511 virtual memory regions that can be reserved before 
the system reports that it’s out of memory. Take, for example, the following code 
fragment: 


ddefine PAGESIZE 1024 // Assume we're on a 1-KB page machine 
for (i = 0; i < 512; i++) 
pMem[Li] = VirtualAlloc (NULL, PAGESIZE, MEM_RESERVE | MEM_COMMIT, 
PAGE_READWRITE); 


This code attempts to allocate 512 one-page blocks of virtual memory. Even if you 
have half a megabyte of RAM available in the system, VirtualAlloc will fail before the 
loop completes because it will run out of virtual address space for the application. 
This happens because each 1-KB block is allocated on a 64-KB boundary. Since the 
code, stack, and local heap for an application must also be mapped into the same, 
32-MB virtual address space, available virtual allocation regions usually top out at 
about 490. 


361 


Part Il 


362 


A better way to make 512 distinct virtual allocations is to do something like this: 


dKdefine PAGESIZE 1024 #// Assume we're on a 1-KB page machine. 


// Reserve a region first. 
pMemBase = VirtualAlloc (NULL, PAGESIZE * 512, MEM_RESERVE, 
PAGE_NOACCESS); 


< 512; i++) 
VirtualAlloc (pMemBase + (i*PAGESIZE), PAGESIZE, 
MEM_COMMIT, PAGE_READWRITE) ; 


for (i = @; 7 
pMem[Li] = 
This code first reserves a region; the pages are committed later. Because the region 
was first reserved, the committed pages aren’t rounded to 64-KB boundaries, and so, 
if you have 512 KB of available memory in the system, the allocations will succeed. 
Although the code I just showed you is a contrived example (there are better 
ways to allocate 1-KB blocks than directly allocating virtual memory), it does dem- 
onstrate a major difference (from other Windows systems) in the way memory allo- 
cation works in Windows CE. In Windows NT, applications have a full 2-GB virtual 
address space with which to work. In Windows CE however, a programmer should 
remain aware of the relatively small 32-MB virtual address per application. 


Freeing virtual memory 
You can decommit or free virtual memory by calling VirtualFree. Decommitting a page 
unmaps the page from a physical page of RAM but keeps the page or pages reserved. 
The function is prototyped as 


BOOL VirtualFree (LPVOID lpAddress, DWORD dwSize, 
DWORD dwFreeType) ; 


The /pAddress parameter should contain a pointer to the virtual memory region that’s 
to be freed or decommitted. The dwSize parameter contains the size, in bytes, of the 
region if the region is to be decommitted. If the region is to be freed, this value must 
be 0. The dwFreeType parameter contains the flags that specify the type of opera- 
tion. The MEM_DECOMMIT flag specifies that the region will be decommited but will 
remain reserved. The MEM_RELEASE flag both decommits the region if the pages are 
committed and also frees the region. 

All the pages in a region being freed by means of VirtualFree must be in the 
same state. That is, all the pages in the region to be freed must either be committed 
or reserved. VirtualFree fails if some of the pages in the region are reserved while 
some are committed. To free a region with pages that are both reserved and commit- 


ted, the committed pages should be decommitted first, and then the entire region can 
be freed. 
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Changing and querying access rights 

You can modify the access rights of a region of virtual memory, initially specified in 
VirtualAlloc, by calling VirtualProtect. This function can change the access rights only 
on committed pages. The function is prototyped as 


BOOL VirtualProtect (LPVOID lpAddress, DWORD dwSize, 
DWORD flNewProtect, PDWORD Ipfl0OldProtect); 


The first two parameters, JpAddress and dwSize, specify the block and the size of the 

region that the function acts on. The /flNewProtect parameter contains the new pro- 

tection flags for the region. These flags are the same ones I mentioned when I ex- 

plained the VirtualAlloc function. The /pflOldProtect parameter should point to a 

DWORD that will receive the old protection flags of the first page in the region. 
The current protection rights of a region can be queried with a call to 


DWORD VirtualQuery (LPCVOID lIpAddress, 
PMEMORY_BASIC_INFORMATION JpBuffer, 
DWORD dwLength); 


The /pAddress parameter contains the starting address of the region being queried. 
The /pBuffer pointer points to a PMEMORY_BASIC_INFORMATION structure that 
Pll talk about soon. The third parameter, dwLength, must contain the size of the 
PMEMORY_BASIC_INFORMATION structure. 

The PMEMORY_BASIC_INFORMATION structure is defined as 


typedef struct _MEMORY_BASIC_INFORMATION { 
PVOID BaseAddress; 
PVOID AllocationBase; 
DWORD AllocationProtect; 
DWORD RegionSize; 
DWORD State; 
DWORD Protect; 
DWORD Type; 
} MEMORY_BASIC_INFORMATION; 


The first field of MEMORY_BASIC_INFORMATION, BaseAddress, is the address 
passed to the VirtualQuery function. The AllocationBase field contains the base 
address of the region when it was allocated using a VirtualAlloc function. 
The AllocationProtect field contains the protection attributes for the region when it 
was originally allocated. The RegionSize field contains the number of bytes from the 
pointer passed to VirtualQuery to the end of series of pages that have the same 
attributes. The State field contains the state—free, reserved, or committed—of the 
pages in the region. The Protect field contains the current protection flags for the 
region. Finally, the Type field contains the type of memory in the region. This field 
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can contain the flags MEM_PRIVATE, indicating that the region contains private data 
for the application; MEM_MAPPED, indicating that the region is mapped to a memory- 
mapped file; or MEM_IMAGE, indicating that the region is mapped to an EXE or DLL 
module. 

The best way to understand the values returned by VirtualQuery is to look at 
an example. Say an application uses VirtualAlloc to reserve 16,384 bytes (16 pages 
on a 1-KB page-size machine). The system reserves this 16-KB block at address 
OxA0000. Later, the application commits 9216 bytes (9 pages) starting 2048 bytes (2 
pages) into the initial region. Figure 6-3 shows a diagram of this scenario. 


A4000 


A2C00 


Pages orginally 
reserved by 


committed 


[pAddress value passed —> AOSOO 
to VirtualQuery 


A0000 
Figure 6-3. A region of reserved virtual memory that has nine pages committed. 


If a call is made to VirtualQuery with the [pAddress pointer pointing 4 pages 
into the initial region (address 0xA1000), the returned values would be the following: 


BaseAddress 0xA1000 

AllocationBase QxA0000 

AllocationProtect PAGE_NOACCESS 

RegionSize 0x1C00 (7,168 bytes or 7 pages) 
State MEM_COMMIT 

Protect | PAGE_READWRITE 

Type MEM_PRIVATE 


The BaseAddress field contains the address passed to VirtualQuery, 0xA1000, 
4096 bytes into the initial region. The AllocationBase field contains the base address of 
the original region while AllocationProtect contains PAGE_NOACCESS, indicating that 
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the region was originally reserved, not directly committed. The RegionSize field con- 
tains the number of bytes from the pointer passed to VirtualQuery, 0xA1000 to the 
end of the committed pages at 0xA2C00. The State and Protect fields contain the flags 
indicating the current state of the pages. The Type field indicates that the region was 
allocated by the application for its own use. 


Heaps 


Clearly, allocating memory on a page basis is inefficient for most applications. To 
optimize memory use, an application needs to be able to allocate and free memory 
on a per byte, or at least a per 4-byte, basis. The system enables allocations of this 
size through heaps. Using heaps also protects an application from having to deal with 
the differing page sizes of the microprocessors that support Windows CE. An appli- 
cation can simply allocate a block in a heap and the system deals with the number of 
pages necessary for the allocation. 

As I mentioned before, heaps are regions of reserved virtual memory space 
managed by the system for the application. The system gives you a number of func- 
tions that allow you to allocate and free blocks within the heap with a granularity 
much smaller than a page. As memory is allocated by the application within a heap, 
the system automatically grows the size of the heap to fill the request. As blocks in 
the heap are freed, the system looks to see if an entire page is freed. If so, that page 
is decommitted. 

Unlike Windows NT or Windows 98, Windows CE supports the allocation of 
only fixed blocks in the heap. This simplifies the handling of blocks in the heap, but 
it can lead to the heaps becoming fragmented over time as blocks are allocated and 
freed. The result can be a heap being fairly empty but still requiring a large number 
of virtual pages because the system can’t reclaim a page from the heap unless it’s 
completely free. 

Each application has a default, or local, heap created by the system when the 
application is launched. Blocks of memory in the local heap can be allocated, freed, 
and resized using the LocalAlloc, LocalFree, and Localkealloc functions. An applica- 
tion can also create any number of separate heaps. These heaps have the same prop- 
erties as the local heap but are managed through a separate set of Heapxxxx functions. 


The Local Heap 


By default, Windows CE initially reserves 384 pages, or 393,216 bytes, for the local 
heap but only commits the pages as they are allocated. If the application allocates 
more than the 384 KB in the local heap, the system allocates more space for the local 
heap. Growing the heap might require a separate, disjointed address space reserved 
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for the additional space on the heap. Applications shouldn’t assume that the local 
heap is contained in one block of virtual address space. Because Windows CE heaps 
support only fixed blocks, Windows CE implements only the subset of the Win32 local 
heap functions necessary to allocate, resize, and free fixed blocks on the local heap. 


Allocating memory on the local heap 
You allocate a block of memory on the local heap by calling 


HLOCAL LocalAlloc (UINT uFlags, UINT uBytes); 


The call returns a value cast as an HLOCAL, which is a handle to a local memory block, 
but since the block allocated is always fixed, the return value can simply be recast as 
a pointer to the block. 

The uFlags parameter describes the characteristics of the block. The flags sup- 
ported under Windows CE are limited to those that apply to fixed allocations. They 
are the following: 


M JLMEM_FIXED Allocates a fixed block in the local heap. Since all local 
heap allocations are fixed, this flag is redundant. 


M JLMEM_ZEROINIT Initializes memory contents to 0. 
M JIPTR Combines the LMEM_FIXED and LMEM_ZEROINIT flags. 


The uBytes parameter specifies the size of the block to allocate in bytes. The 
size of the block is rounded up, but only to the next DWORD G byte) boundary. 


Freeing memory on the local heap 
You can free a block by calling 


HLOCAL LocalFree (HLOCAL hMem); 


The function takes the handle to the local memory block and returns NULL if suc- 
cessful. If the function fails, it returns the original handle to the block. 


Resizing and querying the size of local heap memory 
You can resize blocks on the local heap by calling 


HLOCAL LocalReAlloc (HLOCAL hMem, UINT uBytes, UINT uFlag); 


The bMem parameter is the pointer (handle) returned by LocalAlloc. The uBytes pa- 
rameter is the new size of the block. The uFlag parameter contains the flags for the 
new block. Under Windows CE, two flags are relevant, LMEM_ZEROINIT and LMEM_ 
MOVEABLE. LMEM_ZEROINIT causes the contents of the new area of the block to 
be set to 0 if the block is grown as a result of this call. The LMEM_MOVEABLE flag 
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tells Windows that it can move the block if the block is being grown and there’s not 

enough room immediately above the current block. Without this flag, if you don’t 

have enough space immediately above the block to satisfy the request, LocalRealloc 

will fail with an out-of-memory error. If you specify the LMEM_MOVEABILE flag, the 

handle (really the pointer to the block of memory) might change as a result of the call. 
The size of the block can be queried by calling 


UINT LocalSize (HLOCAL hMem) ; 


The size returned will be at least as great as the requested size for the block. As I 
mentioned earlier, Windows CE rounds the size of a local heap allocation up to the 
next 4-byte boundary. 


Separate Heaps 


To avoid fragmenting the local heap, it’s better to create a separate heap if you need 
a series of blocks of memory that will be used for a set amount of time. An example 
of this would be a text editor that might manage a file by creating a separate heap for 
each file it’s editing. As files are opened and closed, the heaps would be created and 
destroyed. 

Heaps under Windows CE have the same API as those under Windows NT or 
Windows 98. The only noticeable difference is the lack of support for the HEAP_ 
GENERATE_EXCEPTIONS flag. Under Windows NT, this flag causes the system to 
generate an exception if an allocation request can’t be accommodated. 

A subtle, but more important difference to the programmer is how Windows CE 
manages heaps. While the heap API looks like the standard Win32 heap API, Win- 
dows CE doesn’t implement the functions as you might expect. For example, the 
HeapCreate function has parameters that allow a program to specify how much 
memory to allocate and reserve for a heap. Windows CE ignores these values. In fact, 
simply creating a heap doesn’t allocate or reserve any memory. Memory is reserved 
and committed only when the first block of the heap is allocated. 

Under most conditions, going through the details about when heap memory is 
reserved and committed would seem like nitpicking. But if you’ve used up the 32-MB 
virtual address space for other uses, a heap might not have the virtual address space 
available for the allocation even if you thought you had reserved enough using the 
HeapCreate call. On the other hand, Windows CE doesn’t use the reserved param- 
eter in the HeapCreate call as a hard-coded limit on the size of the heap. Windows CE 
accommodates almost any heap allocation request if the memory is available. Well, 
enough editorializing: on to the heap API. 
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Creating a separate heap 
You create heaps by calling 


Se Ee ee 


DWORD dwMaximumSize); 


Under Windows CE, the first parameter, flOptions, can be NULL, or it can contain the 
HEAP_NO_SERIALIZE flag. By default, Windows heap management routines prevent 
two threads in a process from accessing the heap at the same time. This serialization 
prevents the heap pointers that the system uses to track the allocated blocks in the 
heap from being corrupted. In other versions of Windows the HEAP_NO_SERIALIZE 
flag can be used if you don’t want this type of protection. Under Windows CE how- 
ever, this flag is only provided for compatibility and all heap accesses are serialized. 

The other two parameters, dwinitialSize and dwMaximumsSize, specify the ini- 
tial size and expected maximum size of the heap. Windows NT and Windows 98 use 
the dwMaximumSize value to determine how many pages in the virtual address space 
to reserve for the heap. You can set this parameter to 0 if you want to defer to Win- 
dows’ determination of how many pages to reserve. The dwinitialSize parameter is 
then used to determine how many of those initially reserved pages will be immedi- 
ately committed. As I mentioned, while these two size parameters are documented 
exactly the same way as their counterparts under Windows NT and 98, the current 
version of Windows CE doesn’t actually use them. You should, however, use valid 
numbers to retain compatibility with future versions of Windows CE that might use 
these parameters. 


Allocating memory in a separate heap 
You allocate memory on the heap using 


LPVOID HeapAlloc (HANDLE hHeap, DWORD dwFlags, DWORD dwBytes); 


Notice that the return value is a pointer, not a handle as in the LocalAlloc function. 
Separate heaps always allocate fixed blocks, even under Windows NT and Win- 
dows 98. The first parameter is the handle to the heap returned by the HeapCreate 
call. The dwFlags parameter can be one of two self-explanatory values, HEAP_NO_ 
SERIALIZE and HEAP_ZERO_MEMORY. The final parameter, dwBytes, specifies the 
number of bytes in the block to allocate. The size is rounded up to the next DWORD. 


Freeing memory in a separate heap 
You can free a block in a heap by calling 


BOOL HeapFree (HANDLE hHeap, DWORD dwFlags, LPVOID 1pMem); 


The only flag allowable in the dwFlags parameter is HEAP_NO_SERIALIZE. The pMem 
parameter points to the block to free, while bHeap contains the handle to the heap. 
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Resizing and querying the size of memory in a separate heap 
You can resize heap allocations by calling 


LPVOID HeapReAlloc (HANDLE hHeap, DWORD dwFlags, LPVOID 1pMem, 
DWORD dwBytes); 


The dwFlags parameter can be any combination of three flags: HEAP_NO_SERIALIZE, 
HEAP_REALLOC_IN_PLACE_ONLY, and HEAP_ZERO_MEMORY. The only new flag 
here is HEAP_REALLOC_IN_PLACE_ONLY, which tells the heap manager to fail the 
reallocation if the space can’t be found for the block without relocating it. This flag is 
handy if you already have a number of pointers pointing to data in the block and 
you aren’t interested in updating them. The /bMem parameter is the pointer to the 
block being resized, and the dwBytes parameter is the requested new size of the block. 
Notice that the function of the HEAP_REALLOC_IN_PLACE_ONLY flag in HeapReAlloc 
provides the opposite function from the one that the LMEM_MOVEABLE flag pro- 
vides for LocalReAlloc. HEAP_REALLOC_IN_PLACE_ONLY prevents a block that would 
be moved by default in a separate heap while LAEM_MOVEABLE enables a block 
to be moved that by default would not be moved in the local heap. HeapReAlloc re- 
turns a pointer to the block if the reallocation was successful, and returns NULL oth- 
erwise. Unless you specified that the block not be relocated, the returned pointer might 
be different from the pointer passed in if the block had to be relocated to find enough 
space in the heap. 
To determine the actual size of a block, you can call 


DWORD HeapSize (HANDLE hHeap, DWORD dwFlags, LPCVOID 1pMem) ; 


The parameters are as you expect: the handle of the heap, the single, optional flag, 
HEAP_NO_SERIALIZE, and the pointer to the block of memory being checked. 
Destroying a separate heap 

You can completely free a heap by calling 


BOOL HeapDestroy (HANDLE hHeap); 


Individual blocks within the heap don’t have to be freed before you destroy the heap. 
One final heap function is valuable when writing DLLs. The function 


HANDLE GetProcessHeap (VOID); 


returns the handle to the local heap of the process calling the DLL. This allows a 
DLL to allocate memory within the calling process’s local heap. All the other heap 
calls, with the exception of HeapDestroy, can be used with the handle returned by 
GetProcessHeap. 
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The Stack 
The stack is the easiest to use (the most self-managing) of the different types of memory 
under Windows CE. The stack under Windows CE, as in any operating system, is the 


storage place for temporary variables that are referenced within a function. The op- 
erating system also uses the stack to store return addresses for functions and the state 
of the microprocessor registers during exception handling. 

Windows CE manages a separate stack for every thread in the system. Under 
all versions of the operating system before Windows CE 2.1, each stack in the system 
is limited to fewer than 58 KB. Separate threads within one process can each grow 
its stack up to the 58-KB limit. This limit has to do with how Windows CE manages 
the stack. When a thread is created, Windows CE reserves a 60-KB region for the 
thread’s stack. It then commits virtual pages from the top down as the stack grows. 
As the stack shrinks, the system will, under low-memory conditions, reclaim the un- 
used but still committed pages below the stack. The limit of 58 KB comes from the 
size of the 64-KB region dedicated to the stack minus the number of pages necessary 
to guard the stack against overflow and underflow. 

Starting with Windows CE 2.1, the size of the stack can be specified by a linker 
switch when an application is linked. The same guard pages are applied, but the stack 
size can be specified up to 1 MB. Note that the size defined for the default stack is 
also the size used for all the separate thread stacks. That is, if you specify the main 
stack to be 128 KB, all other threads in the application have a stack size limit of 128 KB. 

One other consideration must be made when you’re planning how to use the 
stack in an application. When an application calls a function that needs stack space, 
Windows CE attempts to commit the pages immediately below the current stack pointer 
to satisfy the request. If no physical RAM is available, the thread needing the stack 
space is briefly suspended. If the request can’t be granted within a short period of 
time, an exception is raised. Windows CE goes to great lengths to free the required 
pages, but if this can’t happen the system raises an exception. [ll cover low-memory 
situations shortly, but for now just remember that you shouldn’t try to use large amounts 
of stack space in low-memory situations. 
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C and C++ applications have predefined blocks of memory that are automatically 
allocated when the application is loaded. These blocks hold statically allocated strings, 
buffers, and global variables as well as buffers necessary for the library functions that 
were statically linked with the application. None of this is new to the C programmer, 
but under Windows CE, these spaces are handy for squeezing the last useful bytes 
out of RAM. 
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Windows CE allocates two blocks of RAM for the static data of an application, 
one for the read/write data and one for the read-only data. Because these areas are 
allocated on a per-page basis, you can typically find some space left over from the 
static data up to the next page boundary. The finely tuned Windows CE application 
should be written to ensure that it has little or no extra space left over. If you have 
space in the static data area, sometimes it’s better to move a buffer or two into the 
static data area instead of allocating those buffers dynamically. 

Another consideration is that if you’re writing a ROM-based application, you 
should move as much data as possible to the read-only static data area. Windows CE 
doesn’t allocate RAM to the read-only area for ROM-based applications. Instead, the 
ROM pages are mapped directly into the virtual address space. This essentially gives 
you unlimited read-only space with no impact on the RAM requirements of the ap- 
plication. 

The best place to determine the size of the static data areas is to look in the 
map file that’s optionally generated by the linker. The map file is chiefly used to deter- 
mine the locations of functions and data for debugging purposes, but it also shows 
the size of the static data, if you know where to look. Figure 6-4 shows a portion of 
an example map file generated by Visual C++. 


memtest 
Timestamp is 34ce4088 (Tue Jan 27 12:16:08 1998) 


Preferred load address is 00010000 


Start Length Name Class 
0001:00000000 G0006100H .text CODE 
0002:00000000 00000310H .rdata DATA 
0002:00000310 00000014H .xdata DATA 
0002:00000324 00000028H .idata$2 DATA 
0002:0000034c 00000014H .idata$3 DATA 
0002:00000360 G00000f4H .idata$4 DATA 
0002:00000454 900003eeH .idata$6 DATA 
0002:00000842 OQ0000000H .edata DATA 
0003:00000000 O00000fF4H .idata$5 DATA 
0003:000000fF4 O8000004H .CRTI$XCA DATA 
0003:000000fF8 G0000004H .CRT$XCZ DATA 
0003:Q@00000fFfc BQ000004H .CRTI$XIA DATA 
0003:00000100 OG000004H .CRT$XIZ DATA 
0003:00000104 @Q0000004H .CRI$XPA DATA 
0003:00000108 Q@Q0000004H .CRTI$XPZ DATA 
0003:0000010c Q0000004H .CRTI$XTA DATA 


(continued) 
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Q003:00000110 QO0000004H .CRI$XTZ DATA 

0003:00000114 @00011e8H .data DATA 

0003:000012fc 9000108cH .bss DATA 

Q204:00900000 920003e8H .ndata DATA 

0005:00000000 O0Q000fOH .rsrc$Ol DATA 

0005:000000f0 00000334H .rsrc$d2 DATA 

Address Publics by Value Rvat+Base Lib:Object 

0001 :00000000 _WinMain 00011000 f memtest.obj 

0001:0000007c _InitApp Q001107c f memtest.obj 

Q001:000000d4 _InitInstance Q00110d4 f memtest.obj 

0001:00000164 _TermInstance 00011164 f memtest.obj 

0001:00000248 _MainWndProc 00011248 f memtest.obj 

0001: 000002b0 _GetFixedEquiv Q00112b0 f  memtest.obj 
f memtest.obj. 


0001 :00000350 _DoCreateMain 00011350 


Figure 6-4. 7he top portion of a map file showing the size of the data segments in an 
application. 


The map file in Figure 6-4 indicates that the EXE has five sections. Section 0001 
is the text segment containing the executable code of the program. Section 0002 
contains the read-only static data. Section 0003 contains the read/write static data. 
Section 0004 contains the fix-up table to support calls to other DLLs. Finally, section 
0005 is the resource section containing the application’s resources, such as menu and 
dialog box templates. 

Let’s examine the .data, .bss, and .rdata lines. The .data section contains the 
initialized read/write data. If you initialized a global variable as in 


static HINST g_hLoadlib = NULL; 


the g_loadlib variable would end up in the .data segment. The .bss segment contains 
the uninitialized read/write data. A buffer defined as 


static BYTE g_ucItems[256]; 


would end up in the .bss segment. The final segment, .rdata, contains the read-only 
data. Static data that you’ve defined using the const keyword ends up in the .rdata 
segment. An example of this would be the structures I use for my message look-up 
tables, as in the following: 


// Message dispatch table for MainWindowProc 
const struct decodeUINT MainMessages[] = { 
WM_CREATE, DoCreateMain, 
WM_SIZE, DoSizeMain, 
WM_COMMAND, DoCommandMain, 
WM_DESTROY, DoDestroyMain, 
3; 
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The .data and .bss blocks are folded into the 0003 section which, if you add 
the size of all blocks in the third section, has a total size of 0x2274, or 8820, bytes. 
Rounded up to the next page size, the read/write section ends up taking nine pages, 
with 396 bytes not used. So, in this example, placing a buffer or two in the static data 
section of the application would be essentially free. The read-only segment, section 
0002, including .rdata, ends up being 0x0842, or 2114, bytes, which takes up three 
pages with 958 bytes, almost an entire page, wasted. In this case, moving 75 bytes of 
constant data from the read-only segment to the read /write segment saves a page of 
RAM when the application is loaded. 


String Resources 


One often forgotten area for read-only data is the resource segment of your applica- 
tion. While I mentioned a new, Windows CE-specific feature of the LoadString func- 
tion in Chapter 3, it’s worth repeating here. If you call LoadString with 0 in place of 
the pointer to the buffer, the function returns a pointer to the string in the resource 
segment. An example would be 


LPCTSTR pString; 


pString = (LPCTSTR)LoadString (hInst, ID_STRING, NULL, @) 


The string returned is read only, but it does allow you to reference the string without 
having to allocate a buffer to hold the string. 


Selecting the Proper Memory Type 


Now that we’ve looked at the different types of memory, it’s time to consider the best 
use of each. For large blocks of memory, directly allocating virtual memory is best. 
An application can reserve as much address space (up to the 32-MB limit of the ap- 
plication) but can commit only the pages necessary at any one time. While directly 
allocated virtual memory is the most flexible memory allocation type, it shifts to us 
the burden of worrying about page granularity as well as keeping track of the reserved 
versus committed pages. 

The local heap is always handy. It doesn’t need to be created and will grow as 
necessary to satisfy a request. Fragmentation is the issue here. Consider that applica- 
tions on an H/PC might run for weeks or even months at a time. There’s no Off but- 
ton on an H/PC or a Palm-size PC—just a Suspend command. So, when you're thinking 
about memory fragmentation, don’t assume that a user will open the application, 
change one item, and then close it. A user is likely to start an application and keep it 
running so that the application is just a quick click away. 

The advantage of separate heaps is that you can destroy them when their time is 
up, nipping the fragmentation problem in the bud. A minor disadvantage of separate 
heaps is the need to manually create and destroy them. Another thing to remember 
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about separate heaps is that Windows CE doesn’t reserve virtual address space when 
a heap is created, which can become an issue if your application uses much of the 
virtual address space available to the application. 

The static data area is a great place to slip in a buffer or two essentially for free 
because the page is going to be allocated anyway. The key to managing the static 
data is to make the size of the static data segments close to, but over the page size of, 
your target processor. For applications written for the H/PC or Palm-size PC, con- 
sider the 1024-byte page size of the NEC MIPS 4100 and Hitachi SH3 processors as 
the default. Sometimes it’s better to move constant data from the read-only segment 
to the read/write segment if it saves a page in the read-only segment. The only time 
you wouldn’t do this is if the application is to be burned into ROM. Then, the more 
constant data, the better, because it doesn’t take up RAM. 

The stack is, well, the stack—simple to use and always around. The only con- 
siderations are the maximum size of the stack and the problems of enlarging the stack 
in alow memory condition. Make sure your application doesn’t require large amounts 
of stack space to shut down. If the system suspends a thread in your application while 
it’s being shut down, the user will more than likely lose data. That won’t help cus- 
tomer satisfaction. 


Managing Low-Memory Conditions 
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Even for applications that have been fine-tuned to minimize their memory use, there 
are going to be times when the system runs very low on RAM. Windows CE applica- 
tions operate in an almost perpetual low-memory environment. The Palm-size PC is 
designed intentionally to run in a low-memory situation Applications on the Palm- 
size PC don’t have a Close button—the shell automatically closes them when the system 
needs additional memory. Because of this, Windows CE offers a number of methods 
to distribute the scarce memory in the system among the running applications. 


The WM_HIBERNATE message 

The first and most obvious addition to Windows CE is the WM_HIBERNATE mes-. 
sage. Windows CE sends this message to all top-level windows that have the WS_ 
OVERLAPPED style (that is, have neither the WS_POPUP nor the WS_CHILD style) 
and have the WS_VISIBLE style. These qualifications should allow most applications 
to have at least one window that receives a WM_HIBERNATE message. An exception 
to this would be an application that doesn’t really terminate, but simply hides all its 
windows. This arrangement allows an application a quick start because it only has to 
show its window, but this situation also means that the application is taking up RAM 
even when the user thinks it’s closed. While this is exactly the kind of application 
design that should not be used under Windows CE, those that are designed this way 
must act as if they’re always in hibernate mode when hidden because they’ll never 
receive a WM_HIBERNATE message. | 
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Windows CE sends WM_HIBERNATE messages to the top-level windows in 
reverse Z-order until enough memory is freed to push the available memory above a 
preset threshold. When an application receives a WM_HIBERNATE message, it should 
reduce its memory footprint as much as possible. This can involve releasing cached 
data; freeing any GDI objects such as fonts, bitmaps, and brushes; and destroying 
any window controls. In essence, the application should reduce its memory use to 
the smallest possible footprint that’s necessary to retain its internal state. 

If sending WM_HIBERNATE messages to the applications in the background 
doesn’t free enough memory to move the system out of a limited-memory state, a 
WM_HIBERNATE message is sent to the application in the foreground. If part of your 
hibernation routine is to destroy controls on your window, you should be sure that 
you aren't the foreground application. Disappearing controls don’t give the user a 
warm and fuzzy feeling. 


Memory thresholds 

Windows CE monitors the free RAM in the system and responds differently as less 
and less RAM is available. As less memory is available, Windows CE first sends 
WM_HIBERNATE messages and then begins limiting the size of allocations possible. 
The two figures below show the free-memory levels used by the Handheld PC and 
the Palm-size PC to trigger low-memory events in the system. Windows CE defines 
four memory states: normal, limited, low, and critical. The memory state of the sys- 
tem depends on how much free memory is available to the system as a whole. These 
limits are higher for 4-KB page systems because those systems have less granularity 
in allocations. 


Event Free Memory Free Memory Comments 
1024-Page Size 4096-Page Size 


Limited- 128 KB 160 KB Send MWM_HIBERNATE 
memory state messages to applications 
in reverse Z-order. 


Free stack space re- 
claimed as needed. 


Low- 64 KB 96 KB Limit virtual allocs to 
memory state 16 KB. 
Low-memory dialog 
displayed. 
Critical- 16 KB 48 KB Limit virtual allocs to 
memory state 8S KB. 


Figure 6-5. Memory thresholds for the Handheld PC. 
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Event Free Memory Free Memory Comments 
1024-Page Size 4096-Page Size 


Hibernate 200 KB | 224 KB Send WM_HIBERNATE 
threshold messages to applications 
in reverse Z-order. | 
Limited- 128 KB 160 KB Begin to close applica- 
memory state tions in reverse Z-order. 


Free stack space re- 
claimed as needed. 


Low- 64 KB 96 KB Limit virtual allocs to 
memory state 16 KB. 

Critical- 16 KB 48 KB Limit virtual allocs to 
memory state S KB. 


Figure 6-6. Memory thresholds for the Palm-size PC. 


The effect of these memory states is to share the remaining wealth. First, 
WM_HIBERNATE messages are sent to the applications to ask them to reduce their 
memory footprint. After an application is sent a WM_HIBERNATE message, the sys- 
tem memory levels are checked to see whether the available memory is now above 
the threshold that caused the WM_HIBERNATE messages to be sent. If not, a 
WM_HIBERNATE message is sent to the next application. This continues until all 
applications have been sent a WM_HIBERNATE message. 

The low-memory strategies of the Handheld PC and the Palm-size PC diverge 
at this point. If the memory level drops below the next threshold, limited for the Palm- 
size PC and Low for the H/PC, the system starts shutting down applications. On 
the H/PC, the system displays the OOM, the out-of-memory dialog, and requests 
that the user either select an application to close or reallocate some RAM dedicated 
to the object store to the program memory. If, after the selected application has been 
shut down or memory has been moved into program RAM, you still don’t have enough 
memory, the out-of-memory dialog is displayed again. This process is repeated until 
there’s enough memory to lift the H/PC above the threshold. 

For the Palm-size PC, the actions are somewhat different. The Palm-size PC shell 
automatically starts shutting down applications in least recently used order without 
asking the user. If there still isn’t enough memory after all applications except the 
foreground application and the shell are closed, the system uses its other techniques 
of scavenging free pages from stacks and limiting any allocations of virtual memory. 

If, on either system, an application is requested to shut down and it doesn’t, 
the system will purge the application after waiting approximately 8 seconds. This is 
the reason an application shouldn’t allocate large amounts of stack space. If the ap- 
plication is shutting down due to low-memory conditions, it’s quite possible that the 
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stack space can’t be allocated and the application will be suspended. If this happens 
after the system has requested that the application close, it could be purged from 
memory without properly saving its state. 

In the low- and critical-memory states, applications are limited in the amount 
of memory they can allocate. In these states, a request for virtual memory larger than 
what’s allowed is refused even if there’s memory available to satisfy the request. 
Remember that it isn’t just virtual memory allocations that are limited; allocations on 
the heap and stack are rejected if, to satisfy the request, those allocations require vir- 
tual memory allocations above the allowable limits. 

I should point out that sending WM_HIBERNATE messages and automatically 
closing down applications is performed by the shell of the H/PC and Palm-size PC. 
The embedded version of Windows CE uses a much simpler shell that doesn’t sup- 
port these memory management techniques. On these embedded systems, you'll have 
to devise your own strategy for managing low-memory situations. 

It should go without saying that applications should check the return codes of 
any memory allocation call, but since some still don’t, I'll say it. Check the return codes 
from calls that allocate memory. There’s a much better chance of a memory alloca- 
tion failing under Windows CE than under Windows NT or Windows 98. Applica- 
tions must be written to react gracefully to rejected memory allocations. 

The Win32 memory management API isn’t fully supported by Windows CE, but 
there’s clearly enough support for you to use the limited memory of a Windows CE 
device to the fullest. A great source for learning about the intricacies of the Win32 
memory management API is Jeff Richter’s Advanced Windows (Microsoft Press, 1997). 
Jeff spends five chapters on memory management while I have summarized the same 
topic in one. 

We’ve looked at the program RAM, the part of RAM that is available to applica- 
tions. Now it’s time, in the next chapter, to look at the other part of the RAM, the 
object store. The object store supports more than a file system. It also supports the 
registry API as well as a database API unique to Windows CE. 
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Files, Databases, 
and the Registry 


One of the areas where Windows CE diverges the farthest from its larger cousins, Win- 
dows NT and Windows 98, is in the area of file storage. Instead of relying on ferromag- 
netic storage media such as floppy disks or hard disk drives, Windows CE implements 
a unique, RAM-based file system known as the object store. In implementation, the 
object store more closely resembles a database than it does a file allocation system 
for a disk. In the object store resides the files as well as the registry for the system 
and any Windows CE databases. Fortunately for the programmer, most of the unique 
implementation of the object store is hidden behind standard Win32 functions. 

The Windows CE file API is taken directly from Win32. Aside from the lack of 
functions that directly reference volumes, the API is fairly complete. Windows CE 
implements the standard registry API, albeit without the vast levels of security found 
in Windows NT. The database API, however, is unique to Windows CE. The database 
functions provide a simple tool for managing and organizing data. They aren’t to be 
confused with the powerful, multilevel SQL databases found on other computers. Even 
with its modest functionality, the database API is convenient for storing and organiz- 
ing simple groups of data, such as address lists or mail folders. 

Some differences in the object store do expose themselves to the program- 
mer. Execute-in-place files, stored in ROM, appear as files in the object store but 
these functions can’t be opened and read as standard files. Some of the ROM-based 
applications are also statically linked to other ROM-based dynamic-link libraries (DLLs). 
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This means that some ROM-based DLLs can’t be replaced by copying an identically 
named file into the object store. 

The concept of the current directory, so important in other versions of Win- 
dows, isn’t present in Windows CE. Files are specified by their complete path. DLLs 
must be in the Windows directory, the root directory of the object store, or in the 
root directory of an attached file storage device, such as a PC Card. 

As a general rule, Windows CE doesn’t support the deep application-level 
security available under Windows NT. However, because the generic Win32 API was 
originally based on Windows NT, a number of the functions for file and registry opera- 
tions have one or more parameters that deal with security rights. Under Windows CE, 
these values should be set to their default, not security state. This means you should 
almost always pass NULL in the security parameters for functions that request security 
information. | 

In this rather long chapter, I’ll first explain the file system and the file API. Then 
Pll give you an overview of the database API. Finally, we’ll do a tour of the registry 
API. The database API is one of the areas that has experienced a fair amount of change 
as Windows CE has evolved. Essentially, functionality has been added to later versions 
of Windows CE. Where appropriate, I’ll cover the differences between the differ- 
ent versions and present workarounds, where possible, for maintaining a common 
code base. 


THE WINDOWS CE FILE SYSTEM 
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The default file system, supported on all Windows CE platforms, is the object store. 
The object store is equivalent to the hard disk on a Windows CE device. It’s a subtly 
complex file storage system incorporating compressed RAM storage for read/write 
files and seamless integration with ROM-based files. A user sees no difference be- 
tween a file in RAM in the object store and those files based in ROM. Files in RAM 
and ROM can reside in the same directory, and document files in ROM can be opened 
(although not modified) by the user. In short, the object store integrates the default 
files provided in ROM with the user-generated files stored in RAM. 

In addition to the object store, Windows CE supports multiple, installable file 
systems that can support up to 256 different storage devices or partitions on storage 
devices. (The limit is 10 storage devices for WIndows CE 2.0 and earlier.) The interface 
to these devices is the installable file system (IFS) API. Most Windows CE platforms 
include an IFS driver for the FAT file system for files stored on ATA flash cards or hard 
disks. In addition, under Windows CE 2.1 and later, third party manufacturers can 
write an IFS driver to support other file systems. 

Windows CE doesn’t use drive letters as is the practice on PCs. Instead, every 
storage device is simply a directory off the root directory. Under Windows CE 1.0, an 
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application can count on the name of the directory of the external drive being PC Card. 
If more than one PC Card was inserted, the additional ones are numbered, as in PC 
Card 1 and PC Card 2, up to PC Card 99 for the 100th card.’ Under Windows CE 2.0, 
the default name was changed from PC Card to Storage Card, but the numbering 
concept stayed the same. For Windows CE 2.1, Windows CE doesn’t assume a name. 
Instead it asks the driver what it wants to call the directory? Later in this chapter, Pll 
demonstrate a method for determining which directories in the root are directories 
and which are actually storage devices. 

As should be expected for a Win32-compatible operating system, the filename 
format for Windows CE is the same as its larger counterparts. Windows CE supports 
long filenames. Filenames and their complete path can be up to MAX_PATH in length, 
which is currently defined at 260 bytes. Filenames have the same name.ext format 
as they do in other Windows operating systems. The extension is the three charac- 
ters following the last period in the filename and defines the type of file. The file 
type is used by the shell when determining the difference between executable files 
and different documents. Allowable characters in filenames are the same as for 
Windows NT and Windows 98. 

Windows CE files support most of the same attribute flags as Windows 98 with 
a few additions. Attribute flags include the standard read-only, system, hidden, com- 
pressed, and archive flags. A few additional flags have been included to support the 
special RAM/ROM mix of files in the object store. 


The Object Store vs. Other Storage Media 


To the programmer, the difference between files in the RAM part of the object store 
and the files based in ROM are subtle. The files in ROM can be detected by a special, 
in-ROM file attribute flag. However, files in the RAM part of the object store that are 
always compressed don’t have the compressed file attribute as might be expected. 
The reason is that the compressed attribute is used to indicate when a file or direc- 
tory is in a compressed state relative to the other files on the drive. In the object store, 
all files are compressed, which makes the compressed attribute redundant. 

The object store in Windows CE has some basic limitations. First, the size of the 
object store is currently limited to 16 MB of RAM. Given the compression features of 
the object store, this means that the amount of data that the object store can contain 
is somewhere around 32 MB. Individual files in the object store are limited to 4 MB 
under Windows CE 2.0 and earlier. Files under Windows CE 2.1 and later are limited 
only by the size of the object store’s 16-MB limit. These file size limits don’t apply to 
files on secondary storage such as hard disks, PC Cards, or Compact Flash Cards. 


1. This limit is 10 cards for Windows CE 2.0 and earlier. 
2. The Handheld PC Pro uses Storage Card as its default name. 
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Standard File I/O 


Windows CE supports the most of the same file I/O functions found on Windows NT 
and Windows 98. The same Win32 API calls, such as CreateFile, ReadFile, WriteFile 
and CloseFile, are all supported. A Windows CE programmer must be aware of a few 
differences, however. First of all, the standard C file I/O functions, such as fopen, fread, 
and fprintf, aren’t supported under Windows CE. Likewise, the old Win16 standards, 
_lread, _lwrite, and _Ilseek, aren’t supported. This isn’t really a huge problem because 
all of these functions can easily be implemented by wrapping the Windows CE file 
functions with a small amount of code. Windows CE 2.1 does support basic console 
library functions such as printf for console applications. 

Windows CE doesn’t support the overlapped I/O that’s supported under Win- 
dows NT. Files or devices can’t be opened with the FILE_LFLAG_OVERLAPPED flag 
nor can reads or writes use the overlapped mode of asynchronous calls and returns. 

File operations in Windows CE follow the traditional handle-based methodol- 
ogy used since the days of MS-DOS. Files are opened by means of a function that 
returns a handle. Read and write functions are passed the handle to indicate the file 
to act on. Data is read from or written to the offset in the file indicated by a system- 
maintained file pointer. Finally, when the reading and writing have been completed, 
the application indicates this by closing the file handle. Now on to the specifics. 


Creating and Opening Files 
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Creating a file or opening an existing file or device is accomplished by means of the 
standard Win32 function: 


HANDLE CreateFile (LPCTSTR lpFileName, DWORD dwDesiredAccess, 
DWORD dwShareMode, 
LPSECURITY_ATTRIBUTES 1pSecurityAttributes, 
DWORD dwCreationDistribution, 
DWORD dwFlagsAndAttributes, HANDLE hTemplateFile); 


The first parameter is the filename of the file to be opened or created. The name of 
the file should have a fully specified path. Filenames with no path information are 
assumed to be in the root directory of the object store. 

The dwDesiredAccess parameter indicate the requested access rights. The allow- 
able flags are GENERIC_READ to request read access to the file and GENERIC_WRITE 
for write access. Both flags must be passed to get read/write access. You can open a 
file with neither read nor write permissions. This is handy if you just want to get the 
attributes of a device. The dwShareMode parameter specifies the access rights that 
can be granted to other processes. This parameter can be FILE_SHARE_READ and/ 
or FILE_SHARE_WRITE. The IpSecurityAttributes parameter is ignored by Windows CE 
and should be set to NULL. 
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The dwCreationDistribution parameter tells CreateFile how to open or create 
the file. The following flags are allowed: 


aul CREATE_NEW Creates a new file. If the file already exists, the function 
fails. 


Pe CREATE_ALWAYS Creates a new file or truncates an existing file. 


OPEN_EXISTING Opens a file only if it already exists. 


M jOPEN_ALWAYS Opens a file or creates a file if it doesn’t exist. This dif- 
fers from CREATE_ALWAYS because it doesn’t truncate the file to 0 bytes 
if the file exists. 


M  TRUNCATE_EXISTING Opens a file and truncates it to 0 bytes. The func- 
tion fails if the file doesn’t already exist. 


The dwFlagsAndAttributes parameter defines the attribute flags for the file if it’s 
being created in addition to flags in order to tailor the operations on the file. The fol- 
lowing flags are allowed under Windows CE: 


M FILE_ATTRIBUTE_NORMAL This is the default attribute. It’s overridden 
by any of the other file attribute flags. 


M £FILE_ATTRIBUTE_READONLY Sets the read-only attribute bit for the file. 
Subsequent attempts to open the file with write access will fail. 


M FILE_ATTRIBUTE_ARCHIVE Sets the archive bit for the file. 


M FILE_ATTRIBUTE_SYSTEM Sets the system bit for the file indicating that 
the file is critical to the operation of the system. 


M FILE_ATTRIBUTE_HIDDEN Sets the hidden bit. The file will be visible 
only to users who have the View All Files option set in the Explorer. 


M FILE_FLAG_WRITE_THROUGH Write operations to the file won't be la- 
zily cached in memory. 


M@ FILE_FLAG_RANDOM_ACCESS Indicates to the system that the file will 
be randomly accessed instead of sequentially accessed. This flag can help 
the system determine the proper caching strategy for the file. 


Windows CE doesn’t support a number of file attributes and file flags that are 
supported under Windows 98 and Windows NT. The unsupported flags include but 
aren’t limited to the following: FILE_LATTRIBUTE_OFFLINE, FILE_FLAG_OVERLAPPED, 
FILE_FLAG_NO_BUFFERING, FILE_FLAG_SEQUENTIAL_SCAN, FILE_FLAG_DELETE_ 

-ON_CLOSE, FILE_FLAG_BACKUP_SEMANTICS, and FILE_FLAG_POSIX_SEMANTICS. 
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Under Windows NT and Windows 98, the flag FILE_LATTRIBUTE_TEMPORARY is used 
to indicate a temporary file, but as we’ll see below, it’s used by Windows CE to indi- 
cate a directory that is in reality a separate drive or network share. 

The final parameter.in CreateFile, hTemplate, is ignored by Windows CE and 
should be set to 0. CreateFile returns a handle to the opened file if the function was 
successful. If the function fails, it returns INVALID_HANDLE_VALUE. To determine 
why the function failed, call GetLastError. If the dwCreationDistribution flags included 
CREATE_ALWAYS or OPEN_ALWAYS, you can determine whether the file previously 
existed by calling GetLastError to see if it returns ERROR_ALREADY_EXISTS. CreateFile 
will set this error code even though the function succeeded. 


Reading and Writing 
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Windows CE supports the standard Win32 functions ReadFile and WriteFile. Reading 
a file is as simple as calling the following: 


BOOL ReadFile (HANDLE hFile, LPVOID 1lpBuffer, 
DWORD nNumberOfBytesToRead, 
LPDWORD 1lpNumberOfBytesRead, LPOVERLAPPED 1pOverlapped) ; 


The parameters are fairly self-explanatory. The first parameter is the handle of the 
opened file to read followed by a pointer to the buffer that will receive the data and 
the number of bytes to read. The fourth parameter is a pointer to a DWORD that will 
receive the number of bytes that was actually read. Finally, the JpOverlapped parameter 
must be set to NULL because Windows CE doesn’t support overlapped file opera- 
tions. As an aside, Windows CE does support multiple reads and writes pending on 
a device; it just doesn’t support the ability to return from the function before the 
operation completes. 

Data is read from the file starting at the file offset indicated by the file pointer. 
After the read has completed, the file pointer is adjusted by the number of bytes read. 

ReadFile won't read beyond the end of a file. If a call to ReadFile asks for more 
bytes than remains in the file, the read will succeed, but only the number of bytes 
remaining in the file will be returned. This is why you must check the variable pointed 
to by IpNumberOfBytesRead after a read completes to learn how many bytes were 
actually read. A call to ReadFile with the file pointer pointing to the end of the file 
results in the read being successful, but the number of read bytes is set to 0. 

Writing to a file is accomplished with this: 


BOOL WriteFile (HANDLE hFile, LPCVOID 1pBuffer, 
/ DWORD nNumberOfBytesToWrite, 
LPDWORD IpNumberOfBytesWritten, 
LPOVERLAPPED 1pOverlapped) ; 
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The parameters are similar to ReadFile with the obvious exception that /pBuffer now 
points to the data that will be written to the file. As in ReadFile, the [pOverlapped 
parameter must be NULL. The data is written to the file offset indicated by the file 
pointer, which is updated after the write so that it points to the byte immediately 
beyond the data written. 


Moving the file pointer 
The file pointer can be adjusted manually with a call to the following: 


DWORD SetFilePointer (HANDLE hFile, LONG 1DistanceToMove, 
PLONG IpDistanceToMoveHigh, DWORD dwMoveMethod) ; 


The parameters for SetFilePointer are the handle of the file; a signed offset distance 
to move the file pointer; a second, upper 32-bit offset parameter; and dwMoveMethod, 
a parameter indicating how to interpret the offset. While /DistanceToMove is a signed 
32-bit value, IpDistanceToMoveHigh is a pointer to a signed 32-bit value. For file pointer 
moves of greater than 4 GB, [pDistanceToMoveHigh should point to a LONG that 
contains the upper 32-bit offset of the move. This variable will receive the high 32 
bits of the resulting file pointer. For moves of less than 4 GB, simply set /pDistance- 
ToMoveHigh to NULL. Clearly, under Windows CE, the JpDistanceToMoveHigh pa- 
rameter is a bit excessive, but having the function the same format as its Windows NT 
counterpart aids in portability across platforms. 

The offset value is interpreted as being from the start of the file if dwMoveMethod 
contains the flag FILE_BEGIN. To base the offset on the current position of the file 
pointer, use FILE_CURRENT. To base the offset from the end of the file, use FILE_LEND 
in dwMoveMethod. 

SetFilePointer returns the file pointer at its new position after the move has been 
accomplished. To query the current file position without changing the file pointer, 
simply call SetFilePointer with a zero offset and relative to the current position in the 
file, as shown here: 


nCurrFilePtr = SetFilePointer (hFile, @, NULL, FILE_CURRENT); 


Closing a file 
Closing a file handle is a simple as calling 


BOOL CloseHandle (HANDLE hObject); 


This generic call, used to close a number of handles, is also used to close file handles. 
The function returns TRUE if it succeeds. If the function fails, a call to GetLastError 
will return the reason for the failure. 
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Truncating a file 

When you have finished writing the data to a file, you can close it with a call to 
CloseHandle and you're done. Sometimes, however, you must truncate a file to make 
it smaller than it currently is. In the days of MS-DOS, the way to set the end of a file 
was to make a call to write zero bytes to a file. The file was then truncated at the 
current file pointer. This won’t work in Windows CE. To set the end of a file, move 
the file pointer to the location in the file where you want the file to end and call: 


BOOL SetEndOfFile (HANDLE hFile); 


Of course, for this call to succeed, you need write access to the file. The function 
returns TRUE if it succeeds. 

To insure that all the data has been written to a storage device and isn’t just 
sitting around in a cache, you can call this function: 


WINBASEAPI BOOL WINAPI FlushFileBuffers (HANDLE hFile); 


The only parameter is the handle to the file you want to flush to the disk, or more 
likely in Windows CE a PC Card. 


Getting file information 
A number of calls allow you to query information about a file or directory. To quickly 
get the attributes knowing only the file or directory name, you can use this function: 


DWORD GetFileAttributes (LPCTSTR IpFileName) ; 


In general, the attributes returned by this function are the same ones that I covered 
for CreateFile, with the addition of the attributes listed below: 


M FILE_ATTRIBUTE_COMPRESSED The file is compressed. 
M FILE_ATTRIBUTE_INROM The file is in ROM. 


M £FILE_ATTRIBUTE_ROMMODULE |The file isan executable module in ROM 
formatted for execute-in-place loading. These files can’t be opened with 
CreateFile. 


M FILE_ATTRIBUTE_DIRECTORY ‘The name specifies a directory, nota file. 


M £FILE_ATTRIBUTE_TEMPORARY When this flag is set in combination with 
FILE_ATTRIBUTE_DIRECTORY, the directory is the root of a secondary 
storage device, such as a PC Card or a hard disk. 


The attribute FILE_ATTRIBUTE_COMPRESSED is somewhat misleading on a 
Windows CE device. Files in the RAM-based object store are always compressed, but 
this flag isn’t set for those files. On the other hand, the flag does accurately reflect 
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whether a file in ROM is compressed. Compressed ROM files have the advantage of 
taking up less space but the disadvantage of not being execute-in-place files. 

An application can change the basic file attributes, such as read only, hidden, 
system, and attribute by calling this function: 


BOOL SetFileAttributes (LPCTSTR IpFileName, DWORD dwFileAttributes) ; 


This function simply takes the name of the file and the new attributes. Note that you 
can’t compress a file by attempting to set its compressed attribute. Under other Win- 
dows systems that do support selective compression of files, the way to compress a 
file is to make a call directly to the file system driver. 

A number of other informational functions are supported by Windows CE. All 
of these functions, however, require a file handle instead of a filename, so the file 
must have been previously opened by means of a call to CreateFile. 


File times 

The standard Win32 API supports three file times: the time the file was created, the 
time the file was last accessed (that is, the time it was last read, written, or executed), 
and the last time the file was written to. That being said, the Windows CE object store 
keeps track of only one time, the time the file was last written to. One of the ways to 
query the file times for a file is to call this function: 


BOOL GetFileTime (HANDLE hFile, LPFILETIME IpCreationTime, 
LPFILETIME IpLastAccessTime, 
LPFILETIME IpLastWriteTime) ; 


The function takes a handle to the file being queried and pointers to three FILETIME 
values that will receive the file times. If you’re interested in only one of the three values, 
the other pointers can be set to NULL. 

When the file times are queried for a file in the object store, Windows CE cop- 
ies the last write time into all FILETIME structures. This goes against Win32 documen- 
tation, which states that any unsupported time fields should be set to 0. For the FAT 
file system used on storage cards, two times are maintained: the file creation time 
and the last write time. When GetFileTime is called on a file on a storage card, the file 
creation and last write times are returned and the last access time is set to 0. 

The FILETIME structures returned by GetFileTime and other functions can be 
converted to something readable by calling 


BOOL FileTimeToSystemTime (const FILETIME *lpFileTime, 
LPSYSTEMTIME 1IpSystemTime) ; 


This function translates the FILETIME structure into a SYSTEMTIME structure that has 
documented day, date, and time fields that can be used. One large caveat is that file 
times are stored in coordinated universal time format (UTC), also known as Greenwich 
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Mean Time. This doesn’t make much difference as long as you’re using unreadable 
FILETIME structures but when you're translating a file time into something readable, 
a call to 
BOOL FileTimeToLocalFileTime (const FILETIME *lpFileTime, 

LPFILETIME lpLocalFileTime) ; 


before translating the file time into system time provides the proper time zone trans- 
lation to the user. 7 
You can manually set the file times of a file by calling 


BOOL SetFileTime (HANDLE hFile, const FILETIME *lpCreationTime, 
const FILETIME «lpLastAccessTime, 
const FILETIME *lpLastWriteTime) ; 


The function takes a handle to a file and three times each in FILETIME format. If you 
want to set only one or two of the times, the remaining parameters can be set to NULL. 
Remember that file times must be in UTC time, not local time. 

For files in the Windows CE object store, setting any one of the time fields re- 
sults in all three being updated to that time. If you set multiple fields to different times 
and attempt to set the times for an object store file, the pLastWriteTime takes prece- 
dence. Files on storage cards maintain separate creation and last-write times. You must 
open the file with write access for SetFileTime to work. 


File size and other information 
You can query a file’s size by calling 


DWORD GetFileSize (HANDLE hFile, LPDWORD 1lpFileSizeHigh) ; 


The function takes the handle to the file and an optional pointer to a DWORD that’s 
set to the high 32 bits of the file size. This second parameter can be set to NULL if 
you don’t expect to be dealing with files over 4 GB. GetFileSize returns the low 32 
bits of the file size. 

I’ve been talking about these last few functions separately, but an additional 
function, GetFileInformationByHandle, returns all this information and more. The 
function prototyped as 


BOOL GetFileInformationByHandle (HANDLE hFile, 
LPBY_HANDLE_FILE_INFORMATION 1lpFileInformation) ; 


takes the handle of an opened file and a pointer to a BY_HANDLE_FILE_ 
INFORMATION structure. The function returns TRUE if it was successful. 
The BY_HANDLE_FILE_INFORMATION structure is defined this way: 


typedef struct _BY_HANDLE_FILE_INFORMATION { 
DWORD dwFileAttributes; 
FILETIME ftCreationTime; 
FILETIME ftLastAccessTime; 
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FILETIME ftLastWriteTime; 
DWORD dwVolumeSerialNumber; 
DWORD nFileSizeHigh; 
DWORD nFileSizeLow; 
DWORD nNumberOfLinks; 
DWORD nFileIndexHigh; 
DWORD nFileIndexLow; 
DWORD dwOID;/ 
} BY_HANDLE_FILE_INFORMATION; 


As you can see, the structure returns data in a number of fields that separate func- 
tions return. I’ll talk about only the new fields here. 

The dwVolumeSerialNumber field is filled with the serial number of the volume 
in which the file resides. The volume is what’s considered a disk or partition under 
Windows 98 or Windows NT. Under Windows CE, the volume refers to the object 
store, a storage card, or a disk on a local area network. For files in the object store, 
the volume serial number is 0. 

The nNumberOfLinks field is used by Windows NT’s NTFS file system and can 
be ignored under Windows CE. The nFileIndexHigh and nFileIndexLow fields con- 
tain a systemwide unique identifier number for the file. This number can be checked 
to see whether two different file handles point to the same file. The File Index value 
is used under Windows NT and Windows 98, but Windows CE has a more useful value, 
the object ID of the file, which is returned in the dwOJD field. ’ll explain the object 
ID later in the chapter; for now I'll just mention that it’s a universal identifier that 
can be used to reference directories, files, databases, and individual database records. 
Handy stuff. 


The FileView Sample Program 


FileView is an example program that displays the contents of a file in a window. It 
displays the data in hexadecimal format instead of text, which makes it different from 
simply opening the file in Microsoft Pocket Word or another editor. FileView is sim- 
ply a file viewer; it doesn’t allow you to modify the file. The code for FileView is shown 
in Figure 7-1. 


Figure 7-1. The Viewer program. (continued) 
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Figure 7-1. continued 
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Figure 7-1. continued 
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Figure 7-1. continued 
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Figure 7-1. continued 
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The C source code is divided into two files, FileView.c and Viewer.c. FileView.c 
contains the standard windows functions and the menu command handlers. In 
Viewer.c, you find the source code for a child window that opens the file and dis- 
plays its contents. The routines of interest are DoOpen Viewer, where the file is opened, 
and ComposeLine, where the file data is read. Both of these routines are in Viewert.c. 
DoOpenViewer uses CreateFile to open the file with read only access. If the function 
succeeds, it calls GetFileSize to query the size of the file being viewed. This is used to 
initialize the range of the view window scrollbar. The window is then invalidated to 
force a WM_PAINT message to be sent. 

In the WM_PAINT handler, OnPaintViewer, a fixed pitch font is selected into 
the device context, and data from the file, starting at the current scroll location, is 
displayed in the window after the application calls the ComposeLine function. This 
routine is responsible for reading the file data into a 4096-byte buffer. The data is 
then read out of the buffer 16 bytes at a time as each line is displayed. If the data for 
the line isn’t in the file buffer, ComposeLine refills the buffer with the proper data from 
the file by calling SetFilePointer and then ReadFile. 
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Memory-Mapped Files and Objects 


Memory-mapped files give you a completely different method for reading and writ- 
ing files. With the standard file I/O functions, files are read as streams of data. To 
access bytes in different parts of a file, the file pointer must be moved to the first byte, 
the data read, the file pointer moved to the other byte, and then the file read again. 

With memory-mapped files, the file is mapped to a region of memory. Then, 
instead of using FileRead and FileWrite, you simply read and write the region of 
memory that’s mapped to the file. Updates of the memory are automatically reflected 
back to the file itself. Setting up a memory-mapped file is a somewhat more complex 
process than making a simple call to CreateFile, but once a file is mapped, reading 
and writing the file is trivial. 


Memory-mapped files 

Windows CE uses a slightly different procedure from Windows NT or Windows 98 to 
access a memory-mapped file. To open a file for memory-mapped access, a new 
function, unique to Windows CE, is used; it’s named CreateFileForMapping. The pro- 
totype for this function is the following: 


HANDLE CreateFileForMapping (LPCTSTR IpFileName, DWORD dwDesiredAccess, 
DWORD dwShareMode, 
LPSECURITY_ATTRIBUTES 1IpSecurityAttributes, 
DWORD dwCreationDisposition, 
DWORD dwFlagsAndAttributes, 
HANDLE hTemplateFile); 


The parameters for this function are similar to those for CreateFile. The filename 
is the name of the file to read. The dwDesiredAccess parameter, specifying the access 
rights to the file, must be a combination of GENERIC_READ and GENERIC_WRITE, 
or it must be 0. The security attributes must be NULL, while the bTemplateFile pa- 
rameter is ignored by Windows CE. Note that Windows CE 2.1 is the first version of 
Windows CE to support write access to memory-mapped files. If you try to use this 
function in versions earlier than 2.1, it will fail if the dwDesiredAccess parameter con- 
tains the GENERIC_WRITE flag. 

The handle returned by CreateFileForMapping can then be passed to 


HANDLE CreateFileMapping (HANDLE hFile, 
LPSECURITY_ATTRIBUTES 1pFileMappingAttributes, 
DWORD flProtect, DWORD dwMaximumSi zeHigh, 
DWORD dwMaximumSizeLow, LPCTSTR 1pName) ; 


This function creates a file mapping object and ties the opened file to it. The first 
parameter for this function is the handle to the opened file. The security attributes 
parameter must be set to NULL under Windows CE. The //Protect parameter should 
be loaded with the protection flags for the virtual pages that will contain the file data. 
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The maximum size parameters should be set to the expected maximum size of the 
object, or they can be set to 0 if the object should be the same size as the file being 
mapped. The /pName parameter allows you to specify a name for the object. This is 
handy when you’re using a memory-mapped file to share information across differ- 
ent processes. Calling CreateFileMapping with the name of an already-opened file- 
mapping object returns a handle to the object already opened instead of creating a 
new one. 

Once a mapping object has been created, a view into the object is created by 
calling 


LPVOID MapViewOfFile (HANDLE hFileMappingObject, DWORD dwDesiredAccess, 
DWORD dwFileOffsetHigh, DWORD dwFile0ffsetLow, 
DWORD dwNumberOfBytesToMap) ; 


MapViewOf/File returns a pointer to memory that’s mapped to the file. The function 
takes as its parameters the handle of the mapping object just opened as well as the 
access rights, which can be FILE_MAP_READ, FILE_MAP_WRITE, or FILE_MAP_ALL_ 
ACCESS. The offset parameters let you specify the starting point within the file that 
the view starts, while the dwNumberO/BytesToMap parameter specifies the size of 
the view window. 

These last three parameters are useful when you’re mapping large objects. In- 
stead of attempting to map the file as one large object, you can specify a smaller view 
that starts at the point of interest in the file. This reduces the memory required be- 
cause only the view of the object, not the object itself, is backed up by physical RAM. 

When you’re finished with the memory-mapped file, a little cleanup is required. 
First a call to 


BOOL UnmapViewOfFile (LPCVOID 1IpBaseAddress); 


unmaps the view to the object. The only parameter is the pointer to the base address 
of the view. 

Next, a call should be made to close the mapping object and the file itself. Both 
these actions are accomplished by means of calls to CloseHandle. The first call should 
be to close the memory-mapped object, and then CloseHandle should be called to 
close the file. 

The code fragment that follows shows the entire process of opening a file for 
memory mapping, creating the file-mapping object, mapping the view, then clean- 
ing up. The routine is written to open the file in read-only mode. This allows the code 
to run under all versions of Windows CE. 


HANDLE hFile, hFileMap; 
PBYTE pFileMen; 
TCHAR szFileName[MAX_PATH]; 


(continued) 
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// Get the filename. 


hFile = CreateFileForMapping (szFileName, GENERIC_READ, 


Crier CuADE DFAN 
FILE_SHARE_READ, NULL, 


OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL | 
FILE_FLAG_RANDOM_ACCESS,0); 


if (hFile != INVALID_HANDLE_VALUE) { 


hFileMap = CreateFileMapping (hFile, NULL, PAGE_READONLY, @, 9, 0); 
if (hFileMap) { 
pFileMem = MapViewOfFile (hFileMap, FILE_MAP_READ, @, @, Q@); 
if (pFileMem) { 
// 
_// Use the data in the file. 
// 


// Start cleanup by unmapping view. 
UnmapViewOfFile (pFileMem) ; 
} 
CloseHandle (hFileMap); 
} 
CloseHandle (hFile); 
j 


Memory-mapped objects 

One of the more popular uses for memory-mapped objects is for interprocess com- 
munication. For this purpose, you don’t need to have an actual file; it’s the shared 
memory that’s important. Windows CE supports entities referred to as unnamed 
memory-mapped objects. These objects are memory-mapped objects that, under Win- 
dows NT and Windows 98, are backed up by the paging file but under Windows CE 
are simply areas of virtual memory with only program RAM to back up the object. 
Without the paging file, these objects can’t be as big as they would be under Win- 
dows NT or Windows 98 but Windows CE does have a way of minimizing the RAM 
required to back up the memory-mapped object. 

You create such a memory-mapped object by eliminating the call to 
CreateFileForMapping and passing a —1 in the handle field of CreateFileMapping. Since 
no file is specified, you must specify the size of the memory-mapped region in the 
maximum size fields of CreateFileMapping. The following routine creates a 16-MB 
region using a memory-mapped file: 


// Create a 16-MB memory mapped object. 
hNFileMap = CreateFileMapping ((HANDLE)-1, NULL, PAGE_READWRITE, 
Q, 0x1000000, NULL); 
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if (hNFileMap) 
// Map in the object. 
pNFileMem = MapViewOfFile (hNFileMap, 
FILE_MAP_WRITE, 0, 0, @); 


The memory object created by the code above doesn’t actually commit 16 MB 
of RAM. Instead, only the address space is reserved. Pages are autocommitted as they’re 
accessed. This process allows an application to create a huge, sparse array of pages 
that takes up only as much physical RAM as is needed to hold the data. At some point, 
however, if you start reading or writing to a greater number of pages, you'll run out 
of memory. When this happens, the system generates an exception. I'll talk about 
how to deal with exceptions in the next chapter. The important thing to remember is 
that if you really need RAM to be committed to a memory-mapped object, you need 
to read each of the pages so that the system will commit physical RAM to that ob- 
ject. Of course, don’t be too greedy with RAM; commit only the pages you abso- 
lutely require. 


Naming a memory-mapped object 

A memory-mapped object can be named by passing a string to CreateFileMapping. 
This isn’t the name of a file being mapped. Instead the name identifies the mapping 
object being created. In the previous example, the region was unnamed. The follow- 
ing code creates a named memory-mapped object named Bob. This name is global 
so that if another process opens a mapping object with the same name, the two pro- 
cesses will share the same memory mapped object. 


// Create a 16-MB memory mapped object. 
hNFileMap = CreateFileMapping ((HANDLE)-1, NULL, PAGE_READWRITE, 
Q, @x10Q00000, TEXT ("Bob")); 
if (hNFileMap) 
// Map in the object. 
pNFileMem = MapViewOfFile (hNFileMap, 
FILE_MAP_WRITE, @, 9, 0); 


The difference between named and unnamed file mapping objects is that a 
named object is allocated only once in the system. Subsequent calls to CreateFile- 
Mapping that attempt to create a region with the same name will succeed, but the 
function will return a handle to the original mapping object instead of creating a new 
one. For unnamed objects, the system creates a new object each time CreateFile- 
Mapping is called. 

When using a memory-mapped object for interprocess communication, processes 
should create a named object and pass the name of the region to the second process, 
not a pointer. While the first process can simply pass a pointer to the mapping region 
to the other process, this isn’t advisable. If the first process frees the memory-mapped 
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file region while the second process is still accessing the file, an exception will oc- 
cur. Instead, the second process should create a memory-mapped object with the same 
name as the initial process. Windows knows to pass a pointer to the same region that 
was opened by the first process. The system also increments a use count to track 
the number of opens. A named memory-mapped object won’t be destroyed until 
all processes have closed the object. This assures a process that the object will re- 
main at least until it closes the object itself. The XTALK example in Chapter 8 pro- 
vides an example of how to use a named memory mapped object for interprocess 
communication. 


Navigating the File System 
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Now that we’ve seen how files are read and written, let’s take a look at how the 
files themselves are managed in the file system. Windows CE supports most of the 
convenient file and directory management APIs, such as CopyFile, MoveFile, and 
CreateDirectory. 


File and directory management 
Windows CE supports a number of functions useful in file and directory management. 
You can move files using MoveFile, copy them using CopyFile, and delete them using 
DeleteFile. You can create directories using CreateDirectory and delete them using 
RemoveDirectory. While most of these functions are straightforward, I should cover 
a few intricacies here. 

To copy a file, call 


BOOL CopyFile (LPCTSTR IpExistingFileName, LPCTSTR IpNewFileName, 
BOOL bFailIfExists); 


The parameters are the name of the file to copy and the name of the destination di- 
rectory. The third parameter indicates whether the function should overwrite the 
destination file if one already exists before the copy is made. 

Files and directories can be moved and renamed using 


BOOL MoveFile (LPCTSTR IpExistingFileName, LPCTSTR IpNewFileNam) ; 


To move a file, simply indicate the source and destination names for the file. The 
destination file must not already exist. File moves can be made within the object store, 
from the object store to an external drive, or from an external drive to the object store. 
MoveFile can also be used to rename a file. In this case, the source and target direc- 
tories remain the same; only the name of the file changes. 

MoveFile can also be used in the same manner to move or rename directories. 
The only exception is that MoveFile can’t move a directory from one volume to an- 
other. Under Windows CE, MoveFile moves a directory and all its subdirectories and 
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files to a different location within the object store or different locations within an- 
other volume. 
Deleting a file is as simple as calling 


BOOL DeleteFile (LPCTSTR IpFileName) ; 


You pass the name of the file to delete. For the delete to be successful, the file must 
not be currently open. 
You can create and destroy directories using the following two functions: 


BOOL CreateDirectory (LPCTSTR IpPathName, 
LPSECURITY_ATTRIBUTES IpSecurityAttributes) ; 


and 
BOOL RemoveDirectory (LPCTSTR IpPathName) ; 


CreateDirectory takes the name of the directory to create and a security parameter 
that should be NULL under Windows CE. RemoveDirectory deletes a directory. The 
directory must be empty for the function to be successful. 


Finding files 
Windows CE supports the basic FindFirstFile, FindNextFile, FindClose procedure for 
enumerating files as is supported under Windows NT or Windows 98. Searching is 
accomplished on a per-directory basis using template filenames with wild card char- 
acters in the template. 

Searching a directory involves first passing a filename template to FindFirsiFile, 
which is prototyped in this way: 


HANDLE FindFirstFile (LPCTSTR IpFileName, 
LPWIN32_FIND_DATA 1pFindFileData) ; 


The first parameter is the template filename used in the search. This filename can 
contain a fully specified path if you want to search a directory other than the root. 
Windows CE has no concept of Current Directory built into it; if no path is specified 
in the search string, the root directory of the object store is searched. 

As would be expected, the wildcards for the filename template are ? and *. 
The question mark (?) indicates that any single character can replace the question 
mark. The asterisk (*) indicates that any number of characters can replace the as- 
terisk. For example, the search string \windows\alarm?.wav would return the files 
\windows\alarm1.wav, \windows\alarm2.wav, and \windows\alarm3.wav. On the 
other hand, a search string of \windows\*.wav would return all files in the windows 
directory that have a wav extension. 

The second parameter of FindFirstFile is a pointer to a WIN32_FIND_DATA struc- 
ture as defined at the top of the following page. 
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typedef struct _WIN32_FIND_DATA { 
DWORD dwFileAttributes; 
FILETIME ftCreationTime; 
FILETIME ftLastAccessTime; 
FILETIME ftLastWriteTime; 
DWORD nFileSizeHigh; 
DWORD nFileSizeLow; 
DWORD dwOID; 
WCHAR cFileNamel MAX_PATH 1]; 
} WIN32_FIND_DATA; 


This structure is filled with the file data for the first file found in the search. The fields 
shown are similar to what we’ve seen. 

If FindFirstFile finds no files or directories that match the template filename, it 
returns INVALID_-HANDLE_VALUE. If at least one file is found, FindFirstFile fills in 
the WIN32_FIND_DATA structure with the specific data for the found file and returns 
a handle value that you use to track the current search. 

To find the next file in the search, call this function: 


BOOL FindNextFile (HANDLE hFindFile, 
LPWIN32_FIND_DATA 1pFindFileData); 


The two parameters are the handle returned by FindFirstFile and a pointer to a find 
data structure. FindNextFile returns TRUE if a file matching the template passed to 
FindFirstFile is found and fills in the appropriate file data in the WIN32_FIND_DATA 
structure. If no file is found, FindNextFile returns FALSE. 

When you’ve finished searching either because FindNextFile returned FALSE or 
because you simply don’t want to continue searching, you must call this function: 


BOOL FindClose (HANDLE hFindFile); 


This function accepts the handle returned by FindFirstFile. \f FindFirstFile returned 
INVALID_ HANDLE_VALUE, you shouldn’t call FindClose. 

The following short code fragment encompasses the entire file search process. 
This code computes the total size of all files in the Windows directory. 


WIN32_FIND_DATA fd; 


HANDLE hFind; 
INT nTotalSize = Q; 


// Start search for all files in the windows directory. 
hFind = FindFirstFile (TEXT ("\\windows\\*.*"), &fd); 


// If a file was found, hFind will be valid. 
if (hFind != INVALID_HANDLE_VALUE) { 
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// Loop through found files. Be sure to process file 
// found with FindFirstFile before calling FindNextFile. 
do { 
// If found file is not a directory, add its size to 
// the total. (Assume that the total size of all files 
// is less than 2 GB.) 
if (!(fd.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY ) ) 
nTotalSize += fd.nFileSizeLow; 


// See if another file exists. 
} while (FindNextFile (hFind, &fd)); 


// Clean up by closing file search handle. 
FindClose (hFind); 
} 


In this example, the windows directory is searched for all files. If the found “file” isn’t 
a directory, that is, if it’s a true file, its size is added to the total. Notice that the return 
handle from FindFirstFile must be checked, not only so that you know whether a file 
was found but also to prevent FindClose from being called if the handle is invalid. 


Determining drives from directories 

As I mentioned at the beginning of this chapter, Windows CE doesn’t support the 
concept of drive letters so familiar to MS-DOS and Windows users. Instead, file stor- 
age devices such as PC Cards or even hard disks are shown as directories in the root 
directory. That leads to the question, “How can you tell a directory from a drive?” 
The newer versions of Windows CE, starting with version 2.1, don’t have a predefined 
name for these other storage devices. Using a predefined name is shaky at best, any- 
way, given that the name was originally PC Card and then changed to Storage Card. 
Instead, you need to look at the file attributes for the directory. Directories that are 
actually secondary storage devices—that is, they store files in a place other than the 
object store—have the file attribute flag FILE_ATTRIBUTE_TEMPORARY set. So, finding 
storage devices on any version of Windows CE is fairly easy as is shown in the fol- 
lowing code fragment: 


WIN32_FIND_DATA fd; 

HANDLE hFind; 

TCHAR szPathLMAX_PATH]; 
ULARGE_INTEGER InTotal, InFree; 


Istrepy (szPath, TEXT ("\\*.#")); 
hFind = FindFirstFile (szPath, &fd); 


if (hFind != INVALID_HANDLE_VALUE) { 


(continued) 
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do { 
if ((fd.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) && 
(fd.dwFileAttributes & FILE_ATTRIBUTE_TEMPORARY)) { 


// Get the disk space statistics for drive. 
GetDiskFreeSpaceEx (fd.cFileName, NULL, &lnTotal, 
&inFree); 
} 
} while (FindNextFile (hFind, &fd)); 
FindClose (hFind); 
j 


This code uses the find first/find next functions to search the root directory for 
all directories with the FILE_ATTRIBUTE_TEMPORARY attribute set. 
Notice in the code I just showed you, the call to this function: 


BOOL GetDiskFreeSpaceEx (LPCWSTR IpDirectoryName, 
PULARGE_INTEGER IpFreeBytesAvailableToCaller, 
PULARGE_INTEGER IpTotalNumberOfBytes, 
PULARGE_INTEGER 1lpTotalNumberOfFreeBytes) ; 


This function provides information about the total size of the drive, and amount of 
free space it contains. The first parameter is the name of any directory on the drive in 
question. This doesn’t have to be the root directory of the drive. GetDiskFreeSpaceEx 
returns three values: the free bytes available to the caller, the total size of the drive, 
and the total free space on the drive. These values are returned in three 
ULARGE_INTEGER structures. These structures contain two DWORD fields named 
LowPart and HighPart. This allows GetDiskFreeSpaceEx to return 64-bit values. Those 
64-bit values can come in handy on Windows NT and Windows 98, where the drives 
can be large. If you aren’t interested in one or more of the fields, you can pass a NULL 
in place of the pointer 
for that parameter. You can also use GetDiskFreeSpaceEx to determine the size of the 
object store. 
Another function that can be used to determine the size of the object store is 


BOOL GetStoreInformation (LPSTORE_INFORMATION lpsi); 


GetStoreInformation takes one parameter a pointer to a STORE_INFORMATION struc- 
ture defined as 


typedef struct STORE_INFORMATION { 
DWORD dwStoreSize; 
DWORD dwFreeSize; 
} STORE_INFORMATION, *LPSTORE_INFORMATION; 


As you can see, this structure simply returns the total size and amount of free space 
in the object store. Why would you use GetStoreInformation when GetDiskFree- 
SpaceEx is available and more general? Because GetDiskFreeSpaceEx wasn’t available 
under Windows CE 1.0 but GetStoreInformation was. 
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That covers the Windows CE file API. As you can see, very little Windows CE-— 
unique code is necessary when you’re working with the object store. Now let’s look 
at an entirely new set of functions, the database API. 


DATABASES 


Windows CE gives you an entirely unique set of database APIs not available under 
the other versions of Windows. The database implemented by Windows CE is simple, 
with only one level and a maximum of four sort indexes, but it serves as an effective 
tool for organizing uncomplicated data, such as address lists or to-do lists. 

Under the first two versions of Windows CE, databases could reside only in the 
object store, not on external media such as PC Cards. Starting with the release of 
Windows CE 2.1 however, Windows CE can now work with databases on PC Cards 
or other storage devices. This new feature required changes to the database API, ef- 
fectively doubling the number of functions with xxxEx database functions now shad- 
owing the original database API. While the newer versions of Windows CE still support 
the original database functions, those functions can be used only with databases stored 
in the object store. 


Basic Definitions 


A Windows CE database is composed of a series of records. Records can contain 
any number of properties. These properties can be one of the data types shown in 


Figure 7-2. 
Data Type Description 
iVal 2-byte signed integer 
uiVal 2-byte unsigned integer 
IVal 4-byte signed integer 
ulVal 4-byte unsigned integer 
FILETIME A time and date structure 
LPWSTR Q-terminated Unicode string 
CEBLOB A collection of bytes 
BOOL* Boolean 
Double* 8-byte signed value 


* This data type supported only under Windows CE 2.1 and later 


Figure 7-2. Database data types supported by Windows CE. 
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Records can’t contain other records. Also, records can reside on only one data- 
base. Windows CE databases can’t be locked. However, Windows CE does provide a 

nethod of notifying a process that another thread has modified a database. 

A Windows CE database can have up to four sort indices. These indices are 
defined when the database is created but can be redefined later, although the restruc- 
turing of a database takes a large amount of time. Each sort index by itself results in 
a fair amount of overhead, so you should limit the number of sort indices to what 
you really need. 

In short, Windows CE gives you a basic database functionality that helps appli- 
cations organize simple data structures. The pocket series of Windows CE applica- 
tions provided by Microsoft with the H/PC, H/PC Pro, and the Palm-size PC use the 
database API to manage the address book, the task list, and e-mail messages. So, if 
you have a collection of data, this database API might just be the best method of 
managing that data. 


Designing a database 

Before you can jump in with a call to CeCreateDatabase, you need to think carefully 
about how the database will be used. While the basic limitations of the Windows CE 
database structure rule out complex databases, the structure is quite handy for man- 
aging collections of related data on a small personal device, which, after all, is one of 
the target markets for Windows CE. 

Each record in a database can have as many properties as you need as long as 
they don’t exceed the basic limits of the database structure. The limits are fairly loose. 
An individual property can’t exceed the constant CEDB_MAXPROPDATASIZE, which 
is set to 65,471. A single record can’t exceed CEDB_MAXRECORDSIZE, currently 
defined as 131,072. 


Database volumes 

Starting with Windows CE 2.1, database files can now be stored in volumes instead 
of directly in the object store. A database volume is nothing more than a specially 
formatted file where Windows CE databases can be located. Because database vol- 
umes can be stored on file systems other than the object store, database information 
can be stored on PC Cards or similar external storage devices. The most immediate 
disadvantage of working with database volumes is that they must be first mounted 
and then unmounted after you close the databases within the volume. Essentially, 
mounting the database creates or opens the file that contains one or more databases 
along with the transaction data for those databases. 

There are disadvantages to database volumes aside from the overhead of 
mounting and unmounting the volumes. Database volumes are actual files and there- 
fore can be deleted by means of standard file operations. The volumes are, by de- 
fault, marked as hidden, but that wouldn’t deter the intrepid user from finding and 


Chapter 7 Files, Databases, and the Registry 


deleting a volume in a desperate search for more space on the device. Databases 
created directly within the object store aren’t files and therefore are much more dif- 
ficult for the user to accidentally delete. 


The Database API 


Once you have planned your database, given the restrictions and considerations nec- 
essary to it, the programming can begin. 


Mounting a database volume 
To mount a database volume, call 


BOOL CeMountDBVol (PCEGUID pguid, LPWSTR lpszVol, DWORD dwFlags); 


This function performs a dual purpose: it can create a new volume or open an exist- 
ing volume. The first parameter is a pointer to a guid. CeMountDBVol returns a guid 
that’s used by many of the Ex database functions to identify the location of the data- 
base file. You shouldn’t confuse the CEGUID-type guid parameter in the database 
functions with the GUID type that is used by OLE and parts of the Windows shell. A 
CEGUID is simply a handle that tracks the opened database volume. 

The second parameter in CeMountDBVol is the name of the volume to mount. 
This isn’t a database name, but the name of a file that will contain one or more data- 
bases. Since the parameter is a filename, you should define it in \path\name.ext for- 
mat. The standard extension should be cdb. 

The last parameter, dwFlags, should be loaded with flags that define how this 
function acts. The possible flags are the following: 


M  CREATE_NEW Creates a new database volume. If the volume already 
exists, the function fails. 


M CREATE_ALWAYS Creates a new database volume. If the volume already 
exists, it overwrites the old volume. 


M OPEN_EXISTING Opens a database volume. If the volume doesn’t exist, 
the function fails. 


M  OPEN_ALWAYS Opens a database volume. If the volume doesn’t exist, 
a new database volume is created. 


mi TRUNCATE_EXISTING Opens a database volume and truncates it to 0 
bytes. If the volume already exists, the function fails. 


If the flags resemble the action flags for CreateFile, they should. The actions 
of CeMountDBVol essentially mirror CreateFile except that instead of creating or 
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opening a generic file, CeMountDBVol creates or opens a file especially designed to 
hold databases. 

If the function succeeds, it returns TRUE and the guid is set to a value that is 
then passed to the other database en If the function fails, a call to GetLastError 
returns an error code indicating the reason for the failure. 

Database volumes can be open by more than one process at a time. The sys- 
tem maintains a reference count for the volume. As the last process unmounts a da- 


tabase volume, the system unmounts the volume. 


Enumerated mounted database volumes 
You can determine what database volumes are currently mounted by repeatedly calling 
this function: 


BOOL CeEnumDBVolumes (PCEGUID pguid, LPWSTR IpBuf, DWORD dwSize); 


The first time you call CeEnumDBVolumes, set the guid pointed to by pguid to be 
invalid. You use the CREATE_INVALIDGUID macro to accomplish this. CeEnumDB- 
Volumes returns TRUE if a mounted volume is found and returns the guid and name 
of that volume in the variables pointed to by pguid and IpBuff. The dwSize param- 
eter should be loaded with the size of the buffer pointed to by pBuff. To enumerate 
the next volume, pass the guid returned by the previous call to the function. Repeat 
this process until CeEnumDBVolumes returns FALSE. The code below demonstrates 
this process: 

CEGUID guid; 


TCHAR szVolume[MAX_PATH]; 
INT nCnt = Q; 


CREATE_INVALIDGUID (&guid); 

while (CeEnumDBVolumes (&guid, szVolume, sizeof (szVolume))) { 
// guid contains the guid of the mounted volume, 
// szVolume contains the name of the volume. 
nCnt++; // Count the number of mounted volumes. 

} 


Unmounting a database volume 
When you have completed using the volume, you should unmount it by calling this 
function: 


BOOL CeUnmountDBVol (PCEGUID pguid); 


The function’s only parameter is the guid of a mounted database volume. Calling this 
function is necessary when you no longer need a database volume and you want to 
free system resources. Database volumes are only unmounted when all applications 
that have mounted the volume have called CeUnmountDBVol. 


Chapter 7 Files, Databases, and the Registry 


Using the object store as a database volume 

If you’re writing an application for Windows CE 2.1 or later, you still might want to 
use the new Ex database functions but not want to use a separate database volume. 
Because most of the new Ex functions require a CEGUID that identifies a database 
volume, you need a CEGUID that references the system object store. Fortunately, one 
can be created using this macro: 


CREATE_SYSTEMGUID (PCEGUID pguid); 


The parameter is, of course, a pointer to a CEGUID. The value set in the CEGUID by 
this macro can then be passed to any of the Ex database functions as a placeholder 
for a separate volume CEGUID. Databases created within this system CEGUID are 
actually created directly in the object store as if you were using the old non-Ex data- 
base functions. 


Creating a database 
Creating a database is accomplished by calling one of two functions, CeCreateDatabase 
or CeCreateDatabaseEx. The newer function is CeCreateDatabaseEx and works only 
for Windows CE 2.1 and later. CeCreateDatabase is the proper function to use on 
Windows CE 2.0. First, I’m going to talk about CeCreateDatabase, then I'll talk about 
the expanded functionality of CeCreateDatabaseEx. 

CeCreateDatabase is prototyped as 


CEOID CeCreateDatabase (LPWSTR IpszName, DWORD dwDbaseType, 
WORD wNumSortOrder, 
SORTORDERSPEC * rgSortSpecs); 


The first parameter of the function is the name of the new database. Unlike filenames, 
the database name is limited to 32 characters, including the terminating zero. The 
deDbaseType parameter is a user-defined parameter that can be employed to differ- 
entiate families of databases. For example, you might want to use a common type 
value for all databases that your application creates. This allows them to be easily 
enumerated. At this point, there are no rules for what type values to use. Some ex- 
ample type values used by the Microsoft Pocket suite are listed in Figure 7-3. 


Database Value 

Contacts 24 (18 hex) 
Appointments 25. (19 hex) 
Tasks 26 (1A hex) 
Categories 27 (1B hex) 


Figure 7-3. Predefined database types. 
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The values listed in Figure 7-3 aren’t guaranteed to remain constant; I simply 
wanted to show some typical values. If you use a 4-byte value, it shouldn’t be too 
hard to find a unique database type for your application although there’s no reason 
another application couldn’t use the same type. 

The final two parameters specify the sort specification for the database. The 
parameter wNumSortOrder specifies the number of sort specifications, up to a maxi- 
mum of 4, while the rgSortSpecs parameter points to an array of SORTORDERSPEC 
structures defined as 


typedef struct _SORTORDERSPEC { 
PEGPROPID propid; 
DWORD dwFlags; 

} SORTORDERSPEC; 


The first field in the SORTORDERSPEC structure is a property ID or PEGPROPID. 
A property ID is nothing more than a unique identifier for a property in the database. 
Remember that a property is one field within a database record. The property ID is a 
DWORD value with the low 16 bits containing the data type and the upper 16 bits 
containing an application-defined value. These values are defined as constants and 
are used by various database functions to identify a property. For example, a prop- 
erty that contained the name of a contact might be defined as 


dtdefine PID_NAME MAKELONG (CEVT_LPWSTR, 1) 


The MAKELONG macro simply combines two 16-bit values into a DWORD or LONG. 
The first parameter is the low word or the result, while the second parameter becomes 
the high word. In this case, the CEVT_LPWSTR constant indicates that the property 
contains a string while the second parameter is simply a value that uniquely identi- 
fies the Name property, distinguishing it from other string properties in the record. 
The second field in the SORTORDERSPEC, dwFlags, contains flags that define 
how the sort is to be accomplished. The following flags are defined for this field: 


M CEDB_SORT_DESCENDING The sort is to be in descending order. By 
default, properties are sorted in ascending order. 


MM CEDB_SORT_CASEINSENSITIVE ‘The sort should ignore the case of the 
letters in the string. 


M CEDB_SORT_UNKNOWNFIRST Records without this property are to be 
placed at the start of the sort order. By default, these records are placed 
last. 


A typical database might have three or four sort orders defined. After a database 
is created, these sort orders can be changed by calling CeSetDatabaseInfo. However, 
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this function is quite resource intensive and can take from seconds up to minutes to 
execute on large databases. 

If you want to open a database outside of the object store, you can use the fol- 
lowing function: 


CEOID CeCreateDatabaseEx (PCEGUID pguid, CEDBASEINFO *pInfo); 


This function takes a pguid parameter that identifies the mounted database volume 
where the database is located. The second parameter is a pointer to a CEDBASEINFO 
structure defined as | 


typedef struct _CEDBASEINFO { 

DWORD dwFlags; 

WCHAR szDbaseName[CEDB_MAXDBASENAMELEN ]; 

DWORD dwDbaseType; 

WORD wNumRecords; 

WORD wNumSortOrder; 

DWORD dwSize; 

FILETIME ftLastModified; 

SORTORDERSPEC rgSortSpecs[CEDB_MAXSORTORDER]; 
} CEDBASEINFO; 


As you can see, this structure contains a number of the same parameters passed 
individually to CeCreateDatabase. The szDatabaseName, dwDbaseType, wNumSort- 
Order, and rgSortSpecs fields must be initialized in the same manner as they are when 
you call CeCreateDatabase. 

The dwFlags parameter has two uses. First, it contains flags indicating which 
fields in the structure are valid. The possible values for the dwFlags field are: 
CEDB_VALIDNAME, CEDB_VALIDTYPE, CEDB_VALIDSORTSPEC, and CEDB_VALID- 
DBFLAGS. When you’re creating a database, it’s easier to simply set the dwFlags field 
to CEDB_VALIDCREATE, which is a combination of the flags I just listed. An addi- 
tional flag, CEDB_VALIDMODTIME, is used when this structure is used by 
CeOidGetinfo. 

The other use for the dwFlags parameter is to specify the properties of the da- 
tabase. The only flag currently defined is CEDB_NOCOMPRESS. This flag can be speci- 
fied if you don’t want the database you’re creating to be compressed. By default, all 
databases are compressed, which saves storage space at the expense of speed. By 
specifing the CEDB_NOCOMPRESS flag, the database will be larger but you will be 
able to read and write the database faster. 

You can use CeCreateDatabaseEx but create a database within the object store 
instead of within a separate database volume. The advantage of this strategy is that 
the database itself isn’t created within a file and is therefore safer from a user who 
might delete the database volume. 

The value returned by either CeCreateDatabase or CeCreateDatabaseEx is a 
CEOID. We have seen this kind of value a couple of times so far in this chapter. It’s 
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an ID value that uniquely identifies the newly created database, not just among other 
databases, but also among all files, directories, and even database records in the file 
system. If the value is 0, an error occurred while you were trying to create the data- 


base. You can call GetLastError to diagnose the reason the database creation failed. 


Opening a database 
In contrast to what happens when you create a file, creating a database doesn’t also 
open the database. To do that, you must make an additional call to 


HANDLE CeOpenDatabase(PCEOID poid, LPWSTR lpszName, CEPROPID propid, 
DWORD dwFlags, HWND hwndNotify); 


A database can be opened either by referencing its CEOID value or by referencing 
its name. To open the database by using its name, set the value pointed to by the 
poid parameter to 0 and specify the name of the database using the JpszName pa- 
rameter. If you already know the CEOID of the database, simply put that value in the 
parameter pointed to by poid. If the CEOID value isn’t 0, the functions ignore the 
IpszName parameter. 

The propid parameter specifies which of the sort order specifications should 
be used to sort the database while it’s opened. A Windows CE database can have 
only one active sort order. To use a different sort order, you can open a database again, 
specifying a different sort order. 

The dwFlags parameter can contain either 0 or CEDB_AUTOINCREMENT. If 
CEDB_AUTOINCREMENT is specified, each read of a record in the database results 
in the database pointer being moved to the next record in the sort order. Opening a 
database without this flag means that the record pointer must be manually moved to 
the next record to be read. This flag is helpful if you plan to read the database records 
in sequential order. 

The final parameter is the handle of a window that’s to be notified when an- 
other process or thread modifies the database. This message-based notification al- 
lows you to monitor changes to the database while you have it opened. When a 
database is opened with CeOpenDatabase, Windows CE sends the following three 
messages to notify you of changes. 


M j$.B_CEOID_CREATED A record has been created in the database. 
M $DB_CEOID_CHANGED A record has been changed. 
M DB_CEOID_RECORD_DELETED A record has been deleted. 
These messages are encoded as WM_USER+1, WM_USER+3, and WM_USER+6 


respectively, so be careful not to use these low WM_USER messages for your own 
purposes if you want to have that window monitor database changes. 
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If the function is successful, it returns a handle to the opened database. This handle 
is then used by the other database functions to reference this opened database. If the 
handle returned is 0, the function failed for some reason and you can use GetLastError 
to identify the problem. 

If you’re running under Windows CE 2.1 or later you can use the function: 


HANDLE CeOpenDatabaseEx (PCEGUID pguid, 
PCEOID poid, LPWSTR IpszName, CEPROPID propid, 
DWORD dwFlags, CENOTIFYREQUEST *pRequest) ; 


With a couple of exceptions, the parameters for CeOpenDatabaseEx are the same as 
for CeOpenDatabase. The first difference between the two functions is the extra pointer 
to a guid that identifies the volume in which the database resides. 

The other difference is the method Windows CE uses to notify you of a change 
to the database. Instead of passing a handle to a window that will receive one of three 
WM_USER based messages, you pass a pointer to a CENOTIFYREQUEST structure 
that you have previously filled in. This structure is defined as 


typedef struct _CENOTIFYREQUEST { 
DWORD dwSize; 
HWND hWnd; 
DWORD dwFlags; 
HANDLE hHeap; 
DWORD dwParam; 
} CENOTIFYREQUEST; 


The first field must be initialized to the size of the structure. The )Wnd field 
should be set to the window that will receive the change notifications. The dwFlags 
field specifies how you want to be notified. If you put 0 in this field, you’ll receive 
the same DB_CEIOD_xxx messages that are sent if you’d opened the database with 
CeOpenDatabase. If you put CEDB_EXNOTIFICATION in the dwFlags field, your 
window will receive an entirely new and more detailed notification method. 

Instead of receiving the three DB_CEIOD_ messages, your window receives 
a WM_ DBNOTIFICATION message. When your window receives this message, the 
lParam parameter points to a CENOTIFICATION structure defined as 


typedef struct _CENOTIFICATION { 
DWORD dwSize 
DWORD dwParam; 
UINT uType; 
CEGUID guid; 
CEOID oid; 
CEOID oidParent; 
} CENOTIFICATION; 
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As expected, the dwSize field fills with the size of the structure. The dwParam 
field contains the value passed in the dwParam field in the CENOTIFYREQUEST 
structure. This is an application-defined value that can be used for any purpose. 

The uType field indicates why the WM_DBNOTIFICATION message was sent. 


It will be set to one of the following values: 


M DB_CEOID_CREATED A new file system object was created. 


M DB _CEOID_DATABASE_DELETED The database was deleted from a 
volume. 


M@ DB _CEOID_RECORD_DELETED A record was deleted in a database. 
M DB_CEOID_CHANGED An object was modified. 


The guid field contains the guid for the database volume that the message re- 
lates to while the oid field contains the relevant database record oid. Finally, the 
oidParent field contains the oid of the parent of the oid that the message references. 

When you receive a WM_DBNOTIFICATION message, the CENOTIFICATION 
structure is placed ina memory block that you must free. If you specified a handle to 
a heap in the bHeap field of CENOTIFYREQUEST, the notification structure will be 
placed in that heap; otherwise, the system defined where the structure is placed. 
Regardless of its location, you are responsible for freeing the memory that contains 
the CENOTIFICATION structure. You do this with a call to 


BOOL CeFreeNotification(PCENOTIFYREQUEST pRequest, 
PCENOTIFICATION pNotify); 


The function’s two parameters are a pointer to the original CENOTIFYREQUEST 
structure and a pointer to the CENOTIFICATION structure to free. You must free 
the CENOTIFICATION structure each time you receive a WM_DBNOTIFICATION 
message. 


Seeking (or searching for) a record 

Now that the database is opened, you can read and write the records. But before you 
can read or write a record, you must seek to that record. That is, you must move the 
database pointer to the record you want to read or write. You accomplish this using 


CEOID CeSeekDatabase (HANDLE hDatabase, DWORD dwSeekType, DWORD dwValue, 
LPDWORD lpdwindex); 


The first parameter for this function is the handle to the opened database. The 
dwSeekType parameter describes how the seek is to be accomplished. The param- 
eter can have one of the following values: 
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CEDB_SEEK_CEOID Seek a specific record identified by its object ID. The 
object ID is specified in the dwValue parameter. This type of seek is par- 
ticularly efficient in Windows CE databases. 


CEDB_SEEK_BEGINNING | Seek the n” record in the database. The index 
is contained in the dwValue parameter. 


CEDB_SEEK_CURRENT Seek from the current position 7 records forward 
or backward in the database. The offset is contained in the dwValue pa- 
rameter. Even though dwValue is typed as a unsigned value, for this seek 
it’s interpreted as a signed value. 


CEDB_SEEK_END Seek backward from the end of the database n records. 
The number of records to seek backward from the end is specified in the 
dwValue parameter. 


CEDB_SEEK_VALUESMALLER Seek from the current location until a 
record is found that contains a property that is the closest to, but not equal 
to or over the value specified. The value is specified by a CEPROPVAL 
structure pointed to by dwValue. 


CEDB_SEEK_VALUEFIRSTEQUAL _ Starting with the current location, seek 
until a record is found that contains the property that’s equal to the value 
specified. The value is specified by a CEPROPVAL structure pointed to by 
dwValue. The location returned can be the current record. 


CEDB_SEEK_VALUENEXTEQUAL Starting with the next location, seek 
until a record is found that contains a property that’s equal to the value 
specified. The value is specified by a CEPROPVAL structure pointed to by 
dwValue. 


CEDB_SEEK_VALUEGREATER Seek from the current location until a 
record is found that contains a property that is equal to, or the closest to, 
the value specified. The value is specified by a CEPROPVAL structure 
pointed to by dwValue. 


As you can see from the available flags, seeking in the database is more than 


just moving a pointer; it also allows you to search the database for a particular record. 


As I just mentioned in the descriptions of the seek flags, the dwValue param- 


typedef struct _CEPROPVAL { 


CEPROPID propid; 


eter can either be loaded with an offset value for the seeks or point to a property 
value for the searches. The property value is described in a CEPROPVAL structure 
defined as 


(continued) 
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WORD wLenData; 

WORD wFlags; 

CEVALUNION val; 
} CEPROPVAL; 


The propid field should contain one of the property ID values you defined for 
the properties in your database. Remember that the property ID is a combination of 
a data type identifier along with an application specific ID value that uniquely iden- 
tifies a property in the database. This field identifies the property to examine when 
seeking. The wlenData field is ignored. None of the defined flags for the wFlags field 
is used by CeSeekDatabase, so this field should be set to 0. The val field is actually a 
union of the different data types supported in the database. 

Following is a short code fragment that demonstrates seeking to the third record 
in the database. 


DWORD dwIndex; 
CEOID oid; 


// Seek to the third record. 
oid = CeSeekDatabase (g_hDB, CEDB_SEEK_BEGINNING, 3, &dwIndex); 
if (oid == 0) { 
// There is no third item in the database. 
} 


Now say we want to find the first record in the database that has a height prop- 
erty of greater than 100. For this example, assume the size property type is a signed 
long value. 


// Define pid for height property as a signed long with ID of one. 
#define PID_HEIGHT MAKELONG (CEVT_I4, 1) 


CEOID oid; 
DWORD dwIindex; 
CEPROPVAL Property; 


// First seek to the start of the database. 
oid = CeSeekDatabase (g_hDB, CEDB_SEEK_BEGINNING, @, &dwiIndex); 


// Seek the record with height > 100. 


Property.propid = PID_HEIGHT; // Set property to search. 
Property.wLenData = Q; // Not used but clear anyway. 
Property.wFlags = Q; // No flags to set 
Property.val.|lVal = 100; // Data for property 


oid = CeSeekDatabase (g_hDB, CEDB_SEEK_VALUEGREATER, &Property, 
&dwindex) ; 
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if (oid == 0) { 

// No matching property found, db pointer now points to end of db. 
} else { 

// oid contains the object ID for the record, 

// dwIndex contains the offset from the start of the database 

// of the matching record. 


Because the search for the property starts at the current location of the database 
pointer, you first need to seek to the start of the database if you want to find the first 
record in the database that has the matching property. 


Changing the sort order 

I talked earlier about how CeDatabaseSeek depends on the sort order of the opened 
database. If you want to choose one of the predefined sort orders instead, you must 
close the database and then reopen it specifying the predefined sort order. But what 
if you need a sort order that isn’t one of the four sort orders that were defined when 
the database was created? You can redefine the sort orders using this function: 


BOOL CeSetDatabaseInfo (CEOID oidDbase, CEDBASEINFO *pNewInfo); 
or, under Windows CE 2.1 or later, this function: 


BOOL CeSetDatabaseInfoEx (PCEGUID pguid, 
CEOID oidDbase, CEDBASEINFO *pNewInfo); 


Both these functions take the object ID of the database you want to redefine and 
a pointer to a CEDBASEINFO structure. This structure is the same one used by 
CeCreateDatabaseEx. You can use these functions to rename the database, change 
its type, or redefine the four sort orders. You shouldn’t redefine the sort orders casu- 
ally. When the database sort orders are redefined, the system has to iterate through every 
record in the database to rebuild the sort indexes. This can take minutes for large data- 
bases. If you must redefine the sort order of a database, you should inform the user of 
the massive amount of time it might take to perform the operation. 


Reading a record 

Once you have the database pointer at the record you’re interested in, you can read 
or write that record. You can read a record in a database by calling the following 
function: 


CEOQID CeReadRecordProps (HANDLE hDbase, DWORD dwFlags, LPWORD IpcPropID, 
CEPROPID *rgPropID, LPBYTE *lp]pBuffer, 
LPDWORD lpcbBuffer) ; 


or, if you’re running under Windows CE 2.1 or later, by calling the function you see 
at the top of the next page. 
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CEOID CeReadRecordPropsEx (HANDLE hDbase, DWORD dwFlags, 
LPWORD IpcPropID, . 
CEPROPID *rgPropID, LPBYTE *lplpBuffer, 
LPDWORD IpcbBuffer, 
HANDLE hHeap); 


The differences between these two functions is the addition of the bHeap pa- 
rameter in CeReadRecordPropsEx. V'll explain the significance of this parameter shortly. 

The first parameter in these functions is the handle to the opened database. The 
IpcPropID parameter points to a variable that contains the number of CEPROPID struc- 
tures pointed to by the next parameter rgPropID. These two parameters combine to 
tell the function which properties of the record you want to read. There are two ways 
to utilize the JpcPropID and rgPropID parameters. If you want only to read a selected 
few of the properties of a record, you can initialize the array of CEPROPID structures 
with the ID values of the properties you want and set the variable pointed to by 
IpcPropID with the number of these structures. When you call the function, the re- 
turned data will be inserted into the CEPROPID structures for data types such as in- 
tegers. For strings and blobs, where the length of the data is variable, the data is 
returned in the buffer indirectly pointed to by /plpBuffer. 

Since CeReadRecordProps and CeReadRecordPropsEx have a significant over- 
head to read a record, it is always best to read all the properties necessary for a record 
in one call. To do this, simply set rgPropID to NULL. When the function returns, the 
variable pointed to by JpcPropID will contain the count of properties returned and 
the function will return all the properties for that record in the buffer. The buffer will 
contain an array of CEPROPID structures created by the function immediately followed 
by the data for those properties such as blobs and strings where the data isn’t stored 
directly in the CEPROPID array. 

One very handy feature of CeReadRecordProps and CeReadRecordPropsEx is 
that if you set CEDB_ALLOWREALLOC in the dwFlags parameter, the function will 
enlarge, if necessary, the results buffer to fit the data being returned. Of course, for 
this to work, the buffer being passed to the function must not be on the stack or in 
the static data area. Instead, it must be an allocated buffer, in the local heap for 
CeReadkecordProps or in the case of CeReadRecordPropsEx, in the local heap or a 
separate heap. In fact, if you use the CEDB_ALLOWREALLOC flag, you don’t even 
need to pass a buffer to the function, instead you can set the buffer pointer to 0. In 
this case, the function will allocate the buffer for you. | 

Notice that the buffer parameter isn’t a pointer to a buffer but a pointer to a 
pointer to a buffer. There actually is a method to this pointer madness. Since the re- 
sulting buffer can be reallocated by the function, it might be moved if the buffer needs 
to be reallocated. So the pointer to the buffer must be modified by the function. You 
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must always use the pointer the buffer returned by the function because it might have 
changed. Also, you’re responsible for freeing the buffer after you have used it. Even 
if the function failed for some reason, the buffer might have moved or even have been 
freed by the function. You must clean up after the read by freeing the buffer if the 
pointer returned isn’t 0. 

Now to the difference between CeReadRecordProps and CeReadRecordPropsEx. 
As you might have guessed by the above discussion, the extra Heap parameter al- 
lows CekeadRecordPropsEx to use a heap different from the local heap when reallo- 
cating the buffer. When you use CeReadRecordPropsEx and you want to use the local 
heap, simply pass a 0 in the bHeap parameter. 

The routine below reads all the properties for a record, then copies the data 
into a structure. 


int ReadDBRecord (HANDLE hDB, DATASTRUCT *pData) { 
WORD wProps; 
CEOID oid; 
PCEPROPVAL pRecord; 
PBYTE pBuff; 
DWORD dwRecSize; 
int i; 


// Read all properties for the record. 
pBuff = Q; // Let the function allocate the buffer. 
oid = CeReadRecordProps (hDB, CEDB_ALLOWREALLOC, &wProps, NULL, 
&(LPBYTE)pBuff, &dwRecSize); 
// Failure on read. 
if (oid == @) 
return Q; 


// Copy the data from the record to the structure. The order 
// of the array is not defined. 
memset (pData, @ , sizeof (DATASTRUCT)); // Zero return struct 
pRecord = (PCEPROPVAL) pBuff ; // Point to CEPROPVAL 
// array. 
for (i = @; i < wProps; i++) { 
Switch (pRecord->propid) { 
case PID_NAME: 
lstrcpy (pData->szName, pRecord->val.lpwstr); 
break; 
case PID_TYPE: 
Istrcpy (pData->szType, pRecord->val.lpwstr); 
break; 


(continued) 
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case PID_SIZE: 
pData->nSize = pRecord->val.iVal; 
break; 


} 
pRecord++; 
} 
LocalFree (pBuff); 
return i; 
J 


Since the function above reads all the properties for the record, CeReadRecordProps 
creates the array of CEPROPVAL structures. The order of these structures isn’t defined 
so the function cycles through each one to look for the data to fill in the structure. 
After all the data has been read, a call to LocalFree is made to free the buffer that was 
returned by CeReadRecordProps. 

There is no requirement for every record to contain all the same properties. You 
might encounter a situation where you request a specific property from a record by 
defining the CEPROPID array and that property doesn’t exist in the record. When this 
happens, CeReadRecordProps will set the CEDB_PROPNOTFOUND flag in the wFlags 
field of the CEPROPID structure for that property. You should always check for this 
flag if you call CeReadRecordProps and you specify the properties to be read. In the 
example above, all properties were requested, so if a property didn’t exist, no 
CEPROPID structure for that property would have been returned. 


Writing a record 
You can write a record to the database using this function: 


CEOID CeWriteRecordProps (HANDLE hDbase, CEOID oidRecord, WORD cPropID, 
CEPROPVAL * rgPropVal); 


The first parameter is the obligatory handle to the opened database. The oidRecord 
parameter is the object ID of the record to be written. To create a new record instead 
of modifying a record in the database, set oidRecord to 0. The cPropID parameter 
should contain the number of items in the array of property ID structures pointed to 
by rgPropVal. The rcPropVal array specifies which of the properties in the record to 
modify and the data to write. 


Deleting properties, records, and entire databases 
You can delete individual properties in a record using CeWriteRecordProps. To do 
this, create a CEPROPVAL structure that identifies the property to delete and set 
CEDB_PROPDELETE in the wFlags field. 

To delete an entire record in a database, call 


BOOL CeDeleteRecord (HANDLE hDatabase, CEOID oidRecord); 
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The parameters are the handle to the database and the object ID of the record to de- 
lete. : 
You can delete an entire database using this function: 


BOOL CeDeleteDatabase (CEOID oidDbase); 
or, under Windows CE 2.1 or later, this function: 
BOOL CeDeleteDatabaseEx (PCEGUID pguid, CEOID oid); 


The database being deleted can’t be currently open. The difference between the two 
functions is that CeDeleteDatabaseEx can delete databases outside the object store. 


Enumerating databases 

Sometimes you must search the system to determine what databases are on the sys- 
tem. Windows CE provides two sets of functions to enumerate the databases in a 
volume. The first set of these functions works only for databases directly within the 
object store. These functions are 


HANDLE CeFindFirstDatabase (DWORD dwDbaseType) ; 
and 
CEOID CeFindNextDatabase (HANDLE hEnum); 


These functions act like FindFirstFile and FindNextFile with the exception that 
CeFindFirstDatabase only opens the search, it doesn’t return the first database found. 
With these functions the only way to limit the search is to specify the ID of a specific 
database type in the dwDbaseType parameter. If this parameter is set to 0, all data- 
bases are enumerated. CeFindFirstDatabase returns a handle that is then passed to 
CeFindNextDatabase to actually enumerate the databases. 

Below is an example of how to enumerate the databases in the object store. 


HANDLE hDBList; 
CEOID oidDB; 


SendDlgItemMessage (hWnd, IDC_RPTLIST, WM_SETREDRAW, FALSE, @); 


hDBList = CeFindFirstDatabase (Q); 
if (hDBList != INVALID_HANDLE_VALUE) { 


oidDB = CeFindNextDatabase (hDBList); 

while (oidDB) { 
// Enumerated database identified by object ID. 
MyDisplayDatabaseInfo (hCeDB); 


hCeDB = CeFindNextDatabase (hDBList); 


} 
CloseHandle (hDBList); 
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To enumerate databases within a separate database volume, use 
HANDLE CeFindFirstDatabaseEx (PCEGUID pguid, DWORD dwClassID); 
and 
HANDLE CeFindFirstDatabaseEx (PCEGUID pguid, DWORD dwClassID); 


For the most past, these two functions work identically to their non-Ex predecessors 
with the exception that they enumerate the different databases within a single data- 
base volume. The additional parameter in these functions is the CEOZD of the mounted 
volume to search. 


Querying object information 
To query information about a database, use this function: 


BOOL CeOidGetInfo (CEOID oid, CEOIDINFO *poidInfo); 
or, if under Windows CE 2.1 or later, use this function: 
BOOL CeOidGetInfoEx (PCEGUID pguid, CEOID oid, CEOIDINFO *oidInfo); 


These functions return information about not just databases, but any object in the 
file system. This includes files and directories as well as databases and database records. 
The functions are passed the object ID of the item of interest and a pointer to an 
CEOIDINFO structure. Here is the definition of the CEIOIDINFO structure: 


typedef struct _CEOIDINFO { 
WORD wObjType; 
WORD wPad; 
union { 
CEFILEINFO infFile; 
CEDIRINFO infDirectory; 
CEDBASEINFO infDatabase; 
CERECORDINFO infRecord; 
}; 
} CEOIDINFO; 
This structure contains a word indicating the type of the item and a union of four 
different structures each detailing information on that type of object. The currently 
supported flags are: OBJTYPE_FILE, indicating that the object is a file, 
OBJTYPE_DIRECTORY for directory objects, OBJTYPE_DATABASE for database ob- 
jects, and OBJTYPE_RECORD indicating that the object is a record inside a database. 
The structures in the union are specific to each object type. 
The CEFILEINFO structure is defined as 


typedef struct _CEFILEINFO { 
DWORD dwAttributes; 
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CEOID oidParent; 
WCHAR szFileName[MAX_PATH]; 
FILETIME ftLastChanged; 
DWORD dwLength; 

} CEFILEINFO; 


the CEDIRINFO structure is defined as 


typedef struct _CEDIRINFO { 
DWORD dwAttributes; 
CEOID oidParent; 
WCHAR szDirName[MAX_PATH]; 
} CEDIRINFO; 


and the CERECORDINEFO structure is defined as 


typedef struct _CERECORDINFO { 
CEOID oidParent; 
} CERECORDINFO; 


You have already seen the CEDBASEINFO structure used in CeCreateDatabaseEx and 
CeSetDatabaseInfo. As you can see from the above structures, CeGetOidInfo returns 
a wealth of information about each object. One of the more powerful bits of infor- 
mation is the object’s parent oid, which will allow you to trace the chain of files and 
directories back to the root. These functions also allow you to convert an object ID 
into a name of a database, directory, or file. 

The object ID method of tracking a file object should not be confused with the 
PID scheme used by the shell. Object IDs are maintained by the file system, and are 
independent of whatever shell is being used. This would be a minor point under other 
versions of Windows, but with the ability of Windows CE to be built as components 
and customized for different targets, it’s important to know what parts of the operat- 
ing system support which functions. 


The AlbumDB Example Program 


It’s great to talk about the database functions; it’s another experience to use them in 
an application. The example program that follows, AlbumDB, is a simple database 
that tracks record albums, the artist that recorded them, and the individual tracks on 
the albums. It has a simple interface because the goal of the program is to demon- 
strate the database functions, not the user interface. Figure 7-4 on the next page shows 
the AlbumDB window with a few albums entered in the database. 

Figure 7-5 contains the code for the AlbumDB program. When the program is 
first launched, it attempts to open a database called AlbumDB. If one isn’t found, a 
new one is created. This is accomplished in the OpenCreateDB function. 
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Try Anything Once Alan Parsons Project 

Gaudi Alan Parsons Project 

Stereotony Alan Parsons Project 

Vulture Culture Alan Parsons Project 

Ammonia Avenue Alan Parsons Project 

Pyramid Afan Parsons Project 

I Robot Alan Parsons Project 

On Air Alan Parsons Project 

Eve Alan Parsons Project 

Turn of a Friendly Card Alan Parsons Project 

Cosmic Thing B52's 

No Need to Argue Cranberries 

Everybody Else is doing it. Why can't We? Cranberries 

To the Faithful Departed Cranberries 

Communique Dire Straits 

Makeing Movies Dire Straits 

Love over Gold Dire Straits 

Dire Straits Dire Straits 

Brothers in Arms Dire Straits 

One Every Street Dire Straits 

Qn the Boarder Eagles 

Hote! California Eagles 

Desperado Eagles 

Eagles Eagles 

Dulcnea Toad the Wet Sprocket 

In Light Syrup Toad the Wet Sprocket 
Toad the Wet Sprocket 


Figure 7-5. The AlbumDB program. 
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Figure 7-5. continued 
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The program uses a virtual list view control to display the records in the data- 
base. As I explained in Chapter 5, virtual list views don’t store any data internally. 
Instead, the control makes calls back to the owning window using notification mes- 
sages to query the information for each item in the list view control. The WM_NOTIFY 
handler OnNotifyMain calls GetItemData to query the database in response to the 
list view control sending LVN_GETDISPINFO notifications. The GetltemInfo func- 
tion first seeks the record to read then reads all the properties of a database record 
with one call to CeReadRecordProps. Since the list view control typically uses the 
LVN_GETDISPINFO notification multiple times for one item, Get/temInfo saves the 
data from the last record read. If the next read is of the same record, the program 
uses the cached data instead of rereading the database. 

As I’ve explained before, you can change the way you sort by simply closing 
the database and reopening it in one of the other sort modes. The list view control is 
then invalidated, causing it to again request the data for each record being displayed. 
With a new sort order defined, the seek that happens with each database record read 
automatically sorts the data by the sort order defined when the database was opened. 

AlbumDB doesn’t use the new Ex database functions provided by Windows CE 2.1 
based systems. This allows the program to run under earlier versions of the operat- 
ing system. To modify the example to use separate database volumes, only minor 
changes would be necessary. First a global variable g_guidDB of type CEOID would 
be added. In the DoCreateMain routine, code such as the following, which mounts 
the volume, would be added. 
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if (!CeMountDBVol (&g_guidDB, TEXT ("\\Albums.cdb"), OPEN_ALWAYS)) { 
wsprintf (szErr, TEXT ("Database mount failed. rec %d"), 
GetLastError()); 
MessageBox (NULL, szErr, szAppName, MB_OK): 


The following code would be added to the OnDestroyMain routine to unmount 
the volume: 


if (!CHECK_INVALIDGUID (&g_guidDB) ) 
CeUnmountDBVol (&g_guidDB); 


Finally, the OpenCreateDB routine would be replaced by this version: 


HANDLE OpenCreateDB (HWND hWnd, int *pnRecords) { 
INT i, re; 
CEOIDINFO oidinfo; 
CEDBASEINFO dbi; 
TCHAR szErr[128]; 
CENOTIFYREQUEST cenr; 


g_oidDB = Q; 
cenr.dwSize = sizeof (cenr); 
cenr.hWnd = hWnd; 


cenr.dwFlags = Q; // Use old style notifications. 
cenr.hHeap = Q; 
cenr.dwParam = Q; 


g_hDB = CeOpenDatabaseEx (&g_guidDB, &g_oidDB, TEXT ("\\Albums"), 
g_nLastSort, 0, &cenr); 
if (g_hDB == INVALID_HANDLE_VALUE) { 
re = GetLastError(); 
if (re == ERROR_FILE_NOT_FOUND) { 
i = Q@; 
dbi.rgSortSpecs[i].propid = PID_NAME; 
dbi.rgSortSpecs[it++].dwFlags = Q; 


dbi.rgSortSpecs[i].propid = PID_ARTIST; 
dbi.rgSortSpecs[it++].dwFlags = @; 


dbi.rgSortSpecs[i].propid = PID_CATEGORY:; 
dbi.rgSortSpecs[it+].dwFlags = Q@; 


dbi.dwFlags = CEDB_VALIDCREATE; 

lstrepy (dbi.szDbaseName, TEXT ("\\Albums")); 
dbi.dwDbaseType = Q; 

dbi.wNumSortOrder = 3; 


g_oidDB = CeCreateDatabaseEx (&g_guidDB, &dbi); 
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if (g_oidDB == @) { 
wsprintf (szErr, 
TEXT ("Database create failed. rc 4d"), 
GetLastError()); 
MessageBox (hWnd, szErr, szAppName, MB_OK); 
return Q; 
} 
g_hDB = CeOpenDatabaseEx (&g_guidDB, &g_oidDB, NULL, 
g_nLastSort, 0, &cenr); 
} 
} else if (g_hDB == @){ 
wsprintf (szeErr, 
TEXT ("Database open failed. re %X ext err:%d"), 
g_hDB, GetLastError()); 
MessageBox (hWnd, szErr, szAppName, MB_OK); 
} 
CeOidGetInfoEx (&g_guidDB, g_oidDB, &oidinfo); 
*pnRecords = oidinfo.infDatabase.wNumRecords; 
return g_hDB; 


THE REGISTRY 


The registry is a system database used to store configuration information in applica- 
tions and in Windows itself. The registry as defined by Windows CE is similar but not 
identical in function and format to the registries under Windows 98 and Windows NT. 
In other words, for an application, most of the same registry access functions exist, 
but the layout of the Windows CE registry doesn’t exactly follow either Windows 98 
or Windows NT. | 

As in all versions of Windows, the registry is made up of keys and values. Keys 
can contain keys or values or both. Values contain data in one of a number of pre- 
defined formats. Since keys can contain keys, the registry is distinctly hierarchical. 
The highest level keys, the root keys, are specified by their predefined numeric con- 
stants. Keys below the root keys and values are identified by their text name. Mul- 
tiple levels of keys can be specified in one text string by separating the keys with a 
backslash (\). 

To query or modify a value, the key containing the value must first be opened, 
the value queried and or written, then the key closed. Keys and values can also be 
enumerated so that an application can determine what a specific key contains. Data 
in the registry can be stored in a number of different predefined data types. Among 
the available data types are strings, 32-bit numbers, and free form binary data. 
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The Windows CE registry supports three of the high-level, root keys seen on other 
Windows nlatforme HKEY TOCAT. MACHINE HKEY CURRENT USER and HKEY 
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CLASSES_ROOT. As with other Windows platforms, Windows CE uses the 
HKEY_LOCAL_MACHINE key to store hardware and driver configuration data, the 
HKEY_CURRENT_USER to store user-specific configuration data, and the HKEY_ 
CLASSES_ROOT key to store file type matching and OLE configuration data. 

As a practical matter, the registry is used by applications and drivers to store 
state information that needs to be saved across invocations. Applications typically store 
their current state when they are requested to close and then restore this state when 
they are launched again. The traditional location for storing data in the registry by an 
application is obtained by means of the following structure: 


{ROOT_KEY}Software\(Company Name}\iCompany Product} 


In this template, the ROOT_KEY is either HKEY_LOCAL_MACHINE for machine- 
specific data such as what optional components of an application may be installed 
on the machine or HKEY_CURRENT_USER for user-specific information, such as the 
list of the user’s last-opened files. Under the Software key, the company’s name that 
wrote the application is used followed by the name of the specific application. For 
example, Microsoft saves the configuration information for Pocket Word under the key 


HKEY_LOCAL_MACHINE\Software\Microsoft\Pocket Word 


While this hierarchy is great for segregating registry values from different ap- 
plications from one another, it’s best not to create too deep a set of keys. Because of 
the way the registry is designed, it takes less memory to store a value than it does a 
key. Because of this, you should design you registry storage so that it uses fewer 
keys and more values. To optimize even further, it’s more efficient to store more 
information in one value’than to have the same information stored across a num- 
ber of values. 

The window in Figure 7-6 shows the hierarchy of keys used to store data for 
Pocket Word. The left pane shows the hierarchy of keys down to the Settings key 
under the Pocket Word key. In the Settings key, three values are stored: Wrap To 
Window, Vertical Scrollbar Visibility, and Horizontal Scrollbar Visibility. In this case, 
these values are DWORDs, but they could have been strings or other data types. 
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Figure 7-6. You can see the hierarchy of the registry by looking at the values stored by 
Pocket Word. 


The Registry API 


Now let’s turn toward the Windows CE registry API. In general, the registry API pro- 
vides all the functions necessary to read and write data in the registry as well as enu- 
merate the keys and data store within. Windows CE doesn’t support the security 
features of the registry that are supported under Windows NT. 


Opening and creating keys 
A registry key is opened with a call to this function: 


LONG RegOpenKeyEx (HKEY hKey, LPCWSTR IpszSubKey, DWORD ulOptions, 
REGSAM samDesired, PHKEY phkResult); 


The first parameter is the key that contains the second parameter, the subkey. This 
first key must be either one of the root key constants or a previously opened key. 
The subkey to open is specified as a text string that contains the key to open. This 
subkey string can contain multiple levels of subkeys as long as each subkey is sepa- 
rated by a backslash. For example, to open the subkey HKEY_LOCAL_MACHINE)\ 
Software \Microsoft\Pocket Word, an application could either call RegOpenKeyEx 
with HKEY_LOCAL_MACHINE as the key and Software\Microsoft\Pocket Word as 
the subkey or it could open the Software\Microsoft key and then make a call with 
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that opened handle to RegOpenKeyEx specifying the subkey Pocket Word. Key and 
value names aren’t case specific. 

Windows CE ignores the u/Options and samDesired parameters. To remain 
compatible with future versions of the operating system that might use security fea- 
tures, these parameters should be set to 0 for ulOptions and NULL for samDesired. 
The phkResult parameter should point to a variable that will receive the handle to 
the opened key. The function, if successful, returns a value of ERROR_SUCCESS and 
an error code if it fails. 


Another method for opening a key is 


LONG RegCreateKeyEx (HKEY hKey, LPCWSTR IpszSubKey, DWORD Reserved, 
LPWSTR IpszClass, DWORD dwOptions, 
REGSAM samDesired, 
LPSECURITY_ATTRIBUTES 1IpSecurityAttributes, 
PHKEY phkResult, LPDWORD lIpdwDisposition); 


The difference between RegCreateKeyEx and RegOpenKeyEx, aside from the extra 
parameters, is that RegCreateKeyEx creates the key if it didn’t exist before the call. 
The first two parameters, the key handle and the subkey name, are the same as in 
kegOpenKeyEx. The Reserved parameter should be set to 0. The /pClass parameter 
points to a string that contains the class name of the key if it’s to be created. This 
parameter can be set to NULL if no class name needs to be specified. The dwOptions 
and samDesired and IpSecurityAttributes parameters should be set to 0, NULL, and 
NULL respectively. The phkResult parameter points to the variable that receives the 
handle to the opened or newly created key. The /pdwDisposition parameter points 
to a variable that’s set to indicate whether the key was opened or created by the call. 


Reading registry values 
You can query registry values by first opening the key containing the values of inter- 
est and calling this function: 


LONG RegQueryValueEx (HKEY hKey, LPCWSTR lpszValueName, 
LPDWORD IpReserved, LPDWORD IpType, 
LPBYTE lpData, LPDWORD lpcbData); 


The bKey parameter is the handle of the key opened by RegCreateKeyEx or 
RegOpenKeyEx. The lpszValueName is the name of the value that’s being queried. 
The /pType parameter is a pointer to a variable that receives the variable type. This 
variable is filled with The JpData parameter points to the buffer to receive the data, 
while the /pcbData parameter points to a variable that receives the size of the data. If 
RegQueryValueEx is called with the /pData parameter equal to NULL, Windows re- 
turns the size of the data but doesn’t return the data itself. This allows applications to 
first query the size and type of the data before actually receiving it. 
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Writing registry values 
You set a registry value by calling 


LONG RegSetValueEx (HKEY hKey, LPCWSTR IpszValueName, DWORD Reserved, 
DWORD dwlype, const BYTE *lpData, DWORD cbData); 


The parameters here are fairly obvious: the handle to the open key followed by the 
name of the value to set. The function also requires that you pass the type of data, 
the data itself, and the size of the data. The data type parameter is simply a labeling 
aid for the application that eventually reads the data. Data in the registry is stored in 
a binary format and returned in that same format. Specifying a different type has no 
effect on how the data is stored in the registry or how it’s returned to the application. 
However, given the availability of third-party registry editors, you should make ev- 
ery effort to specify the appropriate data type in the registry. 
The data types can be one of the following: 


M i REG_SZ A zero-terminated Unicode string 


M i REG_EXPAND_SZ A zero-terminated Unicode string with embedded 
environment variables 


M REG_MULTI_SZ A series of zero-terminated Unicode strings terminated 
by two zero characters 


REG_DWORD A 4-byte binary value 

REG_BINARY Free-form binary data 

REG_DWORD_BIG_ENDIAN A DWORD value stored in big-endian format 
REG_DWORD_LITTLE_ENDIAN Equivalent to REG_DWORD 

REG_LINK 

REG_NONE 


REG_RESOURCE_LIST 

Deleting keys and values 

You delete a registry key by calling 

LONG RegDeleteKey (HKEY hKey, LPCWSTR IpszSubKey) ; 


The parameters are the handle to the open key and the name of the subkey you plan 
to delete. For the deletion to be successful, the key must not be currently open. You 
can delete a value by calling 


LONG RegDeleteValue (HKEY hKey, LPCWSTR IpszValueName) ; 
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A wealth of information can be gleaned about a key by calling this function: 


LONG RegQueryInfoKey (HKEY hKey, LPWSTR IpszClas pechClass, 
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LPDWORD IpcchMaxSubKeyLen, 

LPDWORD lpcchMaxClassLen, 

LPDWORD lIpcValues, LPDWORD IpcchMaxValueNameLen, 
LPDWORD lpcbMaxValueData, 

LPDWORD IpcbSecurityDescriptor, 

PFILETIME IpftLastWriteTime) ; 
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The only input parameter to this function is the handle to a key. The function returns 
the class of the key, if any, as well as the maximum lengths of the subkeys and val- 
ues under the key. The last two parameters, the security attributes and the last write 
time, are unsupported under Windows CE and should be set to NULL. 


Closing keys 
You close a registry key by calling 


LONG RegCloseKey (HKEY hKey); 


When a registry key is closed, Windows CE flushes any unwritten key data to the 
registry before returning from the call. 


Enumerating registry keys 

In some instances, you'll find it helpful to be able to query a key to see what subkeys 
and values it contains. You accomplish this with two different functions: one to query 
the subkeys, another to query the values. The first function | 


LONG RegEnumKeyEx (HKEY hKey, DWORD dwIndex, LPWSTR IpszName, 
LPDWORD IpcchName, LPDWORD IpReserved, 
LPWSTR IpszClass, 
LPDWORD IpcchClass, PFILETIME IpftLastWriteTime) ; 


enumerates the subkeys of a registry key through repeated calls. The parameters to 
pass the function are the handle of the opened key and an index value. To enumer- 
ate the first subkey, the dwIndex parameter should be 0. For each subsequent call to 
RegEnumKeyEx, dwIndex should be incremented to get the next subkey. When there 
are no more subkeys to be enumerated, RegEnumKeyEx returns ERROR_NO_ 
MORE_ITEMS. 

For each call to RegEnumKeyEx, the function returns the name of the subkey, 
and its classname. The last write time parameter isn’t supported under Windows CE. 

Values within a key can be enumerated with a call to this function: 


LONG RegEnumValue (HKEY hKey, DWORD dwIndex, LPWSTR IpszValueName, 
LPDWORD IpcchValueName, LPDWORD 1]pReserved, 
LPDWORD IpType, LPBYTE IlpData, LPDWORD IpcbData) ; 
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Like RegEnumKey, this function is called repeatedly, passing index values to enumerate 
the different values stored under the key. When the function returns ERROR_NO_ 
MORE_ITEMS, there are no more values under the key. RegEnumValue returns the 


name of the values, the data stored in the value, as well as its data type and the size 
of the data. 


The RegView Example Program 


The following program is a registry viewer application. It allows a user to navigate 
the trees in the registry and examine the contents of the data stored. Unlike RegEdit, 
which is provided by Windows NT and Windows 98, RegView doesn’t let you edit 


the registry. However, such an extension wouldn’t be difficult to make. Figure 7-7 
contains the code for the RegView program. 


Figure 7-7. The RegView program. (continued) 
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Figure 7-7. continued 
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Figure 7-7. continued 
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7-7. continued 


Figure 
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The workhorses of this program are the enumeration functions that query what 
keys and values are under each key. As a key is opened in the tree view control, the 
control sends a WM_NOTIFY message. In response, RegView enumerates the items 
below that key and fills the tree view with the child keys and the list view control 
with the values. 


CONCLUSION 


We have covered a huge amount of ground in this chapter. The file system, while 
radically different under the covers, presents a standard Win32 interface to the pro- 
grammer and a familiar directory structure to the user. The database API is unique to 
Windows CE and provides a valuable function for the information-centric devices that 
Windows CE supports. The registry structure and interface are quite familiar to Win- 
dows programmers and should present no surprises. 

The last two chapters have covered memory and the file system. Now it’s time 
to look at the third part of the kernel triumvirate, processes and threads. As with the 
other parts of Windows CE, the API will be familiar if perhaps a bit smaller. However, 
the underlying architecture of Windows CE does make itself known. 
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Processes 
and Threads 


Like Windows NT, Windows CE is a fully multitasking and multithreaded operating 
system. What does that mean? In this chapter I'll present a few definitions and then 
some explanations to answer that question. 

A process is a single instance of an application. If two copies of Microsoft Pocket 
Word are running, two unique processes are running. Every process has its own, 
protected, 32-MB address space as described in Chapter 6. Windows CE enforces a 
limit of 32 separate processes that can run at any time. 

Each process has at least one thread. A thread executes code within a process. A 
process can have multiple threads running “at the same time.” I put the phrase at the 
same time in quotes because, in fact, only one thread executes at any instant in time. 
The operating system simulates the concurrent execution of threads by rapidly switch- 
ing between the threads, alternatively stopping one thread and switching to another. 


PROCESSES 


Windows CE treats processes differently than does Windows 98 or Windows NT. First 
and foremost, Windows CE has the aforementioned system limit of 32 processes being 
run at any one time. When the system starts, at least four processes are created: NK.EXE, 
which provides the kernel services; FILESYS.EXE, which provides file system services; 
GWES.EXE, which provides the GUI support; and DEVICE.EXE, which loads and 
maintains the device drivers for the system. On most systems, other processes are 
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also started, such as the shell, EXPLORER.EXE, and, if the system is connected to a 
PC, REPLLOG.EXE and RAPISRV.EXE, which service the link between the PC and the 
Windows CE system. This leaves room for about 24 processes that the user or other 
applications that are running can start. While this sounds like a harsh limit, most sys- 
tems don’t need that many processes. A typical H/PC that’s being used heavily might 
have 15 processes running at any one time. 

Windows CE diverges from its desktop counterparts in other ways. Compared 
with processes under Windows 98 or Windows NT, Windows CE processes contain 
much less state information. Since Windows CE supports neither drives nor the con- 
cept of a current directory, the individual processes don’t need to store that informa- 
tion. Windows CE also doesn’t maintain a set of environment variables, so processes 
don’t need to keep an environment block. Windows CE doesn’t support handle in- 
heritance, so there’s no need to tell a process to enable handle inheritance. Because 
of all this, the parameter-heavy CreateProcess function is passed mainly NULLs and 
zeros, with just a few parameters actually used by Windows CE. 

Many of the process and thread-related functions are simply not supported by 
Windows CE because the system doesn’t support certain features supported by Win- 
dows 98 or Windows NT. Since Windows CE doesn’t support an environment, all the 
Win32 functions dealing with the environment don’t exist in Windows CE. While 
Windows CE supports threads, it doesn’t support fibers, a lightweight version of a 
thread supported by Windows NT. So, the fiber API doesn’t exist under Windows CE. 
Some functions aren’t supported because there’s an easy way to work around the lack 
of the function. For example, GetCommandLine doesn’t exist in Windows CE, so an 
application needs to save a pointer to the command line passed to WinMain if it needs 
to access it later. Finally, ExitProcess doesn’t exist under Windows CE. But, as you 
might expect, there’s a workaround that allows a process to close. 

Enough of what Windows CE doesn’t do; let’s look at what you can do with 
Windows CE. 


Creating a Process 
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The function for creating another process is 


BOOL CreateProcess (LPCTSTR lpApplicationName, 
LPTSTR IpCommandLine, 
LPSECURITY_ATTRIBUTES lpProcessAttributes, 
LPSECURITY_ATTRIBUTES lpThreadAttributes, 
BOOL bInheritHandles, DWORD dwCreationFlags, 
LPVOID IpEnvironment, 
LPCTSTR IpCurrentDirectory, 
LPSTARTUPINFO IpStartupInfo, 
LPPROCESS_INFORMATION 1pProcessInformation) ; 


While the list of parameters looks daunting, most of the parameters must be set to 
NULL or 0 because Windows CE doesn’t support security or current directories, 
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nor does it handle inheritance. This results in a function prototype that looks more 
like this: : 


BOOL CreateProcess (LPCTSTR 1lpApplicationName, 
LPTSTR IpCommandLine, NULL, NULL, FALSE, 
DWORD dwCreationFlags, NULL, NULL, NULL, 
LPPROCESS_INFORMATION 1lpProcessInformation) ; 


The parameters that remain start with a pointer to the name of the application to launch. 
Windows CE looks for the application in the following directories, in this order: 


1. The path, if any, specified in the pApplicationName. 


2. For Windows CE 2.1 or later, the path specified in the SystemPath value in 
[HKEY_LOCAL_MACHINE]\Loader. For earlier versions, the root of any 
external storage devices, such as PC Cards. 


The windows directory, (\Windows). 
The root directory in the object store, (\). 


This action is different from Windows NT, where CreateProcess searches for the 
executable only if IpApplicationName is set to NULL and the executable name is passed 
through the Jp>CcommnadLine parameter. In the case of Windows CE, the applica- 
tion name must be passed in the IpApplicaitonName parameter because Windows CE 
doesn’t support the technique of passing a NULL in /pApplicationName with the ap- 
plication name as the first token in the /p>CommandLine parameter. 

The /pCommandLine parameter specifies the command line that will be passed 
to the new process. The only difference between Windows CE and Windows NT in 
this parameter is that under Windows CE the command line is always passed as a 
Unicode string. And, as I mentioned previously, you can’t pass the name of the exe- 
cutable as the first token in p>CommandLine. 

The dwCreationFlags parameter specifies the initial state of the process after it 
has been loaded. Windows CE limits the allowable flags to the following: 


Mm O Creates a standard process. 


M cCREATE_SUSPENDED Creates the process, then suspends the primary 
thread. 


—M DEBUG_PROCESS The process being created is treated as a process being 
debugged by the caller. The calling process receives debug information 
from the process being launched. 


M DEBUG_ONLY_THIS_PROCESS When combined with DEBUG_PROCESS, 
debugs a process but doesn’t debug any child processes that are launched 
by the process being debugged. 
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gS CREATE_NEW_CONSOLE Forces a new console to be created. This is 
supported only in Windows CE 2.1 and later. 


The only other parameter of CreateProcess used by Windows CE is /pProcess- 
Information. This parameter can be set to NULL, or it can point to a PROCESS_ 
INFORMATION structure that’s filled by CreateProcess with information about the new 
process. The PROCESS_INFORMATION structure is defined this way: 


typedef struct _PROCESS_INFORMATION { 
HANDLE hProcess; 
HANDLE hThread; 
DWORD dwProcesslId; 
DWORD dwThreadId; 
} PROCESS_INFORMATION; 


The first two fields in this structure are filled with the handles of the new process and 
the handle of the primary thread of the new process. These handles are useful for 
monitoring the newly created process, but with them comes some responsibility. When 
the system copies the handles for use in the PROCESS_INFORMATION structure, it 
increments the use count for the handles. This means that, if you don’t have any use 
for the handles, the calling process must close them. Ideally, they should be closed 
immediately following a successful call to CreateProcess. I'll describe some good uses 
for these handles later in this chapter in the section, “Synchronization.” 

The other two fields in the PROCESS_INFORMATION structure are filled with 
the process ID and primary thread ID of the new process. These ID values aren’t 
handles but simply unique identifiers that can be passed to Windows functions to iden- 
tify the target of the function. Be careful when using these IDs. If the new process 
terminates and another new one is created, the system can reuse the old ID values. 
You must take measures to assure that ID values for other processes are still identify- 
ing the process you’re interested in before using them. For example, you can, by us- 
ing synchronization objects, be notified when a process terminates. When the process 
terminated, you would then know not to use the ID values for that process. 

Using the create process is simple, as you can see in the following code 
fragment: 


TCHAR szFileName[MAX_PATH]; 
TCHAR szCmdLine[64]; 

DWORD dwCreationFlags; 
PROCESS_INFORMATION pi; 

INT re; 


Istrcpy (szFileName, TEXT ("calc"™)); 
Tstrepy (szCmdLine, TEXT ("")); 
dwCreationFlags = Q@; 
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rc = CreateProcess (szFileName, szCmdLine, NULL, NULL, FALSE, 
dwCreationFlags, NULL, NULL, NULL, &pi); 
if (re) { 
CloseHandle (pi.hThread) ; 
CloseHandle (pi.hProcess); 
} 


This code launches the standard Calculator applet found on Handheld PCs and Palm- 
size PCs. Since the file name doesn’t specify a path, CreateProcess will, using the stan- 
dard Windows CE search path, find calc.exe in the \Windows directory. Because I 
didn’t pass a command line to Calc, I could have simply passed a NULL value in 
the /pCmdLine parameter. But I passed a null string in sezCmdLine to differentiate the 
lpCmdLine parameter from the many other parameters in CreateProcess that aren’t 
used. I used the same technique for dwCreationFlags. If the call to CreateProcess is 
successful, it returns a nonzero value. The code above checks for this, and if the call 
was successful, closes the process and thread handles returned in the PROCESS_ 
INFORMATION structure. Remember that this must be done by all Win32 applica- 
tions to prevent memory leaks. 


Terminating a Process 


A process can terminate itself by simply returning from the WinMain procedure. For 
console applications, a simple return from main suffices. Windows CE doesn’t sup- 
port the ExitProcess function found in Windows 98 and Windows NT. Instead, you 
can have the primary thread of the process call ExitThread. Under Windows CE, if 
the primary thread terminates, the process is terminated as well, regardless of what other 
threads are currently active in the process. The exit code of the process will be the exit 
code provided by ExitThread. You can determine the exit code of a process by calling 


BOOL GetExitCodeProcess (HANDLE hProcess, LPDWORD IpExitCode); 


The parameters are the handle to the process and a pointer to a DWORD that receives 
the exit code that was returned by the terminating process. If the process is still run- 
ning, the return code is the constant STILL_ACTIVE. 

You can terminate another process. But while it’s possible to do that, you 
shouldn’t be in the business of closing other processes. The user might not be ex- 
pecting that process to be closed without his or her consent. If you need to terminate 
a process (or close a process, which is the same thing but much nicer a word), the 
following methods can be used. 

If the process to be closed is one that you created, you can use some sort of 
interprocess communication to tell the process to terminate itself. This is the most 
advisable method because you’ve designed the target process to be closed by an- 
other party. Another method of closing a process is to send the main window of the 
process a WM_CLOSE message. This is especially effective on the Palm-size PC, where 
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applications are designed to respond to WM_CLOSE messages by quietly saving their 
state and closing. Finally, if all else fails and you absolutely must close another pro- 
cess, you can use TerminateProcess. 

TerminateProcess is prototyped as 


BOOL TerminateProcess (HANDLE hProcess, DWORD uExitCode); 


The two ‘parameters are the handle of the process to terminate and the exit code the 
terminating process will return. 


Other Processes 
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Of course, to terminate another process, you’ve got to know the handle to that pro- 
cess. You might want to know the handle for a process for other reasons, as well. For 
example, you might want to know when the process terminates. Windows CE sup- 
ports two additional functions that come in handy here (both of which are seldom 
discussed). The first function is OpenProcess, which returns the handle of an already 
running process. OpenProcess is prototyped as 


HANDLE OpenProcess (DWORD dwDesiredAccess, BOOL bInheritHandle, 
DWORD dwProcesslId); 


Under Windows CE, the first parameter isn’t used and should be set to 0. The 
binheritHandle parameter must be set to FALSE because Windows CE doesn’t sup- 
port handle inheritance. The final parameter is the process ID value of the process 
you want to open. 

The other function useful in this circumstance is 


DWORD GetWindowThreadProcessId (HWND hWnd, LPDWORD lpdwProcessId); 


This function takes a handle to a window and returns the process ID for the 
process that created the window. So, using these two functions, you can trace a win- 
dow back to the process that created it. 

Two other functions allow you to directly read from and write to the memory 
space of another process. These functions are 
BOOL ReadProcessMemory (HANDLE hProcess, LPCVOID IpBaseAddress, 


LPVOID IpBuffer, DWORD nSize, 
LPDWORD lpNumberOfBytesRead) ; 


and 


BOOL WriteProcessMemory (HANDLE hProcess, LPVOID IpBaseAddress, 
7 LPVOID IpBuffer, DWORD nSize, 
LPDWORD lpNumberOfBytesWritten) ; 
The parameters for these functions are fairly self-explanatory. The first parameter is 
the handle of the remote process. The second parameter is the base address in the 
other process’s address space of the area to be read or written. The third and fourth 
parameters specify the name and the size of the local buffer in which the data is to 
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be read from or written to. Finally, the last parameter specifies the bytes actually read 
or written. Both functions require that the entire area being read to or written from 
must be accessible. Typically, you use these functions for debugging but there’s no 
requirement that this be their only use. 


THREADS 


A thread is, fundamentally, a unit of execution. That is, it has a stack and a processor 
context, which is a set of values in the CPU internal registers. When a thread is sus- 
pended, the registers are pushed onto the thread’s stack, the active stack is changed 
to the next thread to be run, that thread’s CPU state is pulled off its stack, and the 
new thread starts executing instructions. 

Threads under Windows CE are similar to threads under Windows NT or Win- 
dows 98. Each process has a primary thread. Using the functions that I describe be- 
low, a process can create any number of additional threads within the process. The 
only limit to the number of threads in a Windows CE process is the memory and process 
address space available for the thread’s stack. 

Threads within a process share the address space of the process. Memory allo- 
cated by one thread is accessible to all threads in the process. Threads share the same 
access rights for handles whether they be file handles, memory objects handles, or 
handles to synchronization objects. 

Before Windows CE 2.1, the size of all thread stacks was set at around 58 KB. 
Starting with Windows CE 2.1, the stack size of all threads created within a process is 
set by the linker. (The linker switch for setting the stack size in Microsoft Visual C++ 
is /stack.) Secondary threads under Windows CE 2.1 are created with the same stack 
size as the primary thread. 


The System Scheduler 


Windows CE schedules threads in a preemptive manner. Threads run for a quantum 
or time slice, which is usually 25 milliseconds on H/PCs and Palm-size PCs. (OEMs 
developing custom hardware can specify a different quantum.) After that time, if the 
thread hasn’t already relinquished its time slice and if the thread isn’t a time-critical 
thread, it’s suspended and another thread is scheduled to run. Windows CE chooses 
which thread to run based on a priority scheme. Threads of a higher priority are sched- 
uled before threads of lower priority. 

The rules for how Windows CE allocates time among the threads are quite dif- 
ferent from Windows NT and from Windows 98. Unlike Windows NT, Windows CE 
processes don’t have a priority class. Under Windows NT, a process is created with a 
priority class. Threads derive their priority based on the priority class of their parent 
processes. A process with a higher-priority class has threads that run at a higher pri- 
ority than threads in a lower-priority class process. Threads within a process can then 
refine their priority within that process by setting their relative thread priority. 
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Because Windows CE has no priority classes, all processes are treated as peers. 
Individual threads can have different priorities, but the process that the thread runs 
within doesn’t influence those priorities. Also, unlike Windows NT, the foreground 
thread in Windows CE doesn’t get a boost in priority. 

In Windows CE, a thread can have one of eight priority levels. Those priorities 
are listed below: 


i” THREAD_PRIORITY_TIME_CRITICAL Indicates 3 points above normal 
priority. Threads of this priority aren’t preempted. 


M $$THREAD_PRIORITY_HIGHEST Indicates 2 points above normal priority. 


es THREAD_PRIORITY_ABOVE_NORMAL Indicates 1 point above normal 
priority. 

M THREAD_PRIORITY_NORMAL Indicates normal priority. All threads are 
created with this priority. 


M THREAD_PRIORITY_BELOW_NORMAL Indicates 1 point below normal 
priority. 
Zi THREAD_PRIORITY_LOWEST Indicates 2 points below normal priority. 


= THREAD_PRIORITY_ABOVE_IDLE Indicates 3 points below normal 
priority. 
ald THREAD_PRIORITY_IDLE Indicates 4 points below normal priority. 


All higher-priority threads run before lower-priority threads. This means that 
before a thread set to run at particular priority can be scheduled, all threads that have 
a higher priority must be blocked. A blocked thread is one that’s waiting on some 
system resource or synchronization object before it can continue. Threads of equal 
priority are scheduled in a round-robin fashion. Once a thread has voluntarily given 
up its time slice, is blocked, or has completed its time slice, all other threads of the 
same priority are allowed to run before the original thread is allowed to continue. If 
a thread of higher priority is unblocked and a thread of lower priority is currently 
running, the lower-priority thread is immediately suspended and the higher-priority 
thread is scheduled. Lower-priority threads can never preempt a higher-priority thread. 

There are two exceptions to the rules I just stated. If a thread has a priority 
of THREAD_PRIORITY_TIME_CRITICAL, it’s never preempted, even by another 
THREAD_PRIORITY_TIME_CRITICAL thread. As you can see, a THREAD_PRIORITY_ 
TIME_CRITICAL thread can and will starve everyone else in the system unless writ- 
ten carefully. This priority is reserved by convention for interrupt service threads in 
device drivers, which are written so that each thread quickly performs its task and 
releases its time slice. 
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The other exception to the scheduling rules happens if a low-priority thread owns 
a resource that a higher-priority thread is waiting on. In this case, the low-priority thread 
is temporarily given the higher-priority thread’s priority in a scheme known as prior- 
ity inversion, so that it can quickly accomplish its task and free the needed resource. 

While it might seem that lower-priority threads never get a chance to run in 
this scheme, it works out that threads are almost always blocked, waiting on something 
to free up before they can be scheduled. Threads are always created at THREAD_ 
PRIORITY_NORMAL, so, unless they proactively change their priority level, a thread 
is usually at an equal priority to most of the other threads in the system. Even at the 
normal priority level, threads are almost always blocked. For example, an application’s 
primary thread is typically blocked waiting on messages. Other threads should be 
designed to block on one of the many synchronization objects available to a Win- 
dows CE application. 


Never Do This! 


What’s not supported by the arrangement I just described, or by any other thread- 
based scheme, is code like the following: 


while (bFlag == FALSE) { 

// Do nothing, and spin 
} 
// Now do something. 


This kind of code isn’t just bad manners, since it wastes CPU power, it’s a death sen- 
tence to a battery-powered Windows CE device. To understand why this is impor- 
tant, I need to digress into a quick lesson on Windows CE power management. 

Windows CE is designed so that when all threads are blocked, which happens 
over 90 percent of the time, it calls down to the OEM Abstraction Layer (the equiva- 
lent to the BIOS on an MS-DOS machine) to enter a low-power waiting state. Typi- 
cally, this low-power state means that the CPU is halted; that is, it simply stops 
executing instructions. Because the CPU isn’t executing any instructions, no power- 
consuming reads and writes of memory are performed by the CPU. At this point, the 
only power necessary for the system is to maintain the contents of the RAM and light 
the display. This low-power mode can reduce power consumption by up to 99 per- 
cent of what is required when a thread is running in a well-designed system. 

Doing a quick back-of-the-envelope calculation, say a Palm-size PC is designed 
to run for 15 hours on a couple of AAA batteries. Given that the system turns itself off 
after a few minutes of non-use, this 15 hours translates into a month or two of battery 
life in the device for the user. C’m basing this calculation on the assumption that the 
system indeed spends 90 percent or more of its time in its low-power idle state.) Say 
a poorly written application thread spins on a variable instead of blocking. While this 
application is running, the system will never enter its low-power state. So, instead of 
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900 minutes of battery time (15 hours x 60 minutes/hour), the system spends 100 per- 
cent of its time at full power, resulting in a battery life of slightly over 98 minutes, or 
right at 1.5 hours. So, as you can see, it’s good to have the system in its low-power 
state. 

Fortunately, since Windows applications usually spend their time blocked in a 
call to GetMessage, the system power management works by default. However, if you 
plan on using multiple threads in your application, you must use synchronization 
objects to block threads while they’re waiting. First, let’s look at how to create a thread, 
and then I’ll dive into the synchronization tools available to Windows CE programs. 


Creating a Thread 
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You create a thread by calling this function: 


HANDLE CreateThread (LPSECURITY_ATTRIBUTES IpThreadAttributes, 
DWORD dwStackSize, 
LPTHREAD_START_ROUTINE 1pStartAddress, 
LPVOID IpParameter, DWORD dwCreationFlags, 
LPDWORD 1IpThreadId); 


As with CreateProcess, Windows CE doesn’t support a number of the parameters in 
CreateThread, and so they are set to NULL or 0 as appropriate. For CreateThread, 
the lpThreadAttributes, and dwStackSize parameters aren’t supported. The parameter 
lpThreadAitributes must be set to NULL and dwStackSize is ignored by the system 
and should be set to 0. The third parameter, [pStartAddress, must point to the start of 
the thread routine. The /pParameter parameter in CreateThread is an application- 
defined value that’s passed to the thread function as its one and only parameter. 
The dwCreationFlags parameter can be set to either 0 or CREATE_SUSPENDED. If 
CREATE_SUSPENDED is passed, the thread is created in a suspended state and must 
be resumed with a call to ResumeThread. The final parameter is a pointer toa DWORD 
that receives the newly created thread’s ID value. 
The thread routine should be prototyped this way: 


DWORD WINAPI ThreadFunc (LPVOID IpArg); 


The only parameter is the /pParameter value, passed unaltered from the call to 
CreateThread. The parameter can be an integer or a pointer. Make sure, however, 
that you don’t pass a pointer to a stack-based structure that will disappear when the 
routine that called CreateTbread returns. 

If CreateThread is successful, it creates the thread and returns the handle to the 
newly created thread. As with CreateProcess, the handle returned should be closed 
when you no longer need the handle. Following is a short code fragment that con- 
tains a call to start a thread and the thread routine. 
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// 

HANDLE hThread1; 

DWORD dwThread1lID = Q; 
INT nParameter = 5; 


hThreadl = CreateThread (NULL, 0, Thread2, nParameter, Q, 
&dwlhread1ID); 
CloseHandle (hThread1); 


// Second thread routine 
// 
DWORD WINAPI Thread2 (PVOID pArg) { 


INT nParam = (INT) pArg; 


// 

// Do something here. 
Wis 

17% 

// . 

return 0x15; 


In this code, the second thread is started with a call to CreateThread. The 
nParameter value is passed to the second thread as the single parameter to the thread 
routine. The second thread executes until it terminates, in this case simply by return- 
ing from the routine. 

A thread can also terminate itself by calling this function: 


VOID ExitThread (DWORD dwExitCode) ; 


The only parameter is the exit code that’s set for the thread. That thread exit code 
can be queried by another thread using this function: 


BOOL GetExitCodeThread (HANDLE hThread, LPDWORD 1pExitCode); 


The function takes the handle to the thread (not the thread ID) and returns the exit 
code of the thread. If the thread is still running, the exit code is STILL_ACTIVE, a con- 
stant defined as 0x0103. The exit code is set by a thread using ExitThread or the value 
returned by the thread procedure. In the preceding code, the thread sets its exit code 
to 0x15 when it returns. 

All threads within a process are terminated when the process terminates. As I 
said earlier, a process is terminated when its primary thread terminates. 
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Setting and querying thread priority 

Threads are always created at a priority level of THREAD_ PRIORITY. NORMAL. The 
thread priority can be changed either by the thread itself or by another thread calling 
this function: 


BOOL SetThreadPriority (HANDLE hThread, int nPriority); 


The two parameters are the thread handle and the new priority level. The level passed 
can be one of the constants described previously, ranging from THREAD_PRIORITY_ 
IDLE up to THREAD_PRIORITY_TIME_CRITICAL. You must be extremely careful when 
you're changing a thread’s priority. Remember that threads of a lower priority almost 
never preempt threads of higher priority. So, a simple bumping up of a thread one 
notch above normal can harm the responsiveness of the rest of the system unless that 
thread is carefully written. 
To query the priority level of a thread, call this function: 


int GetThreadPriority (HANDLE hThread); 


This function returns the priority level of the thread. You shouldn’t use the hard-coded 
priority levels. Instead, use constants, such as THREAD_PRIORITY_NORMAL, defined 
by the system. This ensures that any change to the priority scheme in future versions 
of Windows CE doesn’t affect your program. 


Suspending and resuming a thread 
You can suspend a thread at any time by calling this function: 


DWORD SuspendThread (HANDLE hThread) ; 


The only parameter is the handle to the thread to suspend. The value returned is the 
suspend count for the thread. Windows maintains a suspend count for each thread. 
Any thread with a suspend count greater than 0 is suspended. Since SuspendIbread 
increments the suspend count, multiple calls to SuspendThread must be matched with 
an equal number of calls to ResumeThread before a thread is actually scheduled to 
run. ResumeCount is prototyped as 


DWORD ResumeThread (HANDLE hThread); 


Here again, the parameter is the handle to the thread and the return value is 
the previous suspend count. So, if ResumeTbread returns 1, the thread is no longer 
suspended. 

At times, a thread simply wants to kill some time. Since I’ve already explained 
why simply spinning in a while loop is a very bad thing to do, you need another way 
to kill time. The best way to do this is to use this function: 


void Sleep (DWORD dwMilliseconds); 


Sleep suspends the thread for at least the number of milliseconds specified in the 
dwMilliseconds parameter. Since the quantum, or time slice, on a Windows CE 
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system is usually 25 milliseconds, specifying very small numbers of milliseconds 
results in sleeps of at least 25 milliseconds. This strategy is entirely valid, and some- 
times it’s equally valid to pass a 0 to Sleep. When a thread passes a 0 to Sleep, it gives 
up its time slice but is rescheduled immediately according to the scheduling rules I 
described previously. 


Thread Local Storage 


Thread local storage is a mechanism that allows a routine to maintain separate in- 
stances of data for each thread calling the routine. This capability might not seem 
like much, but it has some very handy uses. Take the following thread routine: 


INT g_nGlobal; // System global variable 
int ThreadProc (pStartData) { 

INT nValuel; 

INT nValue2; 


while (unblocked) { 


// 

// Do some work. 

// 
} 
// We're done now, terminate the thread by returning. 
return @; 


i 


For this example, imagine that multiple threads are created to execute the same rou- 
tine, ThreadProc. Each thread has its own copy of nValue1 and nValue2 because 
these are stack-based variables and each thread has its own stack. All threads, though, 
share the same static variable, g nGlobal. 


Now, imagine that the ThreadProc routine calls another routine, WorkerBee. 
As in 


int g_nGlobal; // System global variable 


int ThreadProc (pStartData) { 
int nValuel; 
int nValue2; 
while (unblocked) {f{ 


WorkerBee(); // Let someone else do the work. 
} 
// We're done now, terminate the thread by returning. 
return Q; 


(continued) 
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int WorkerBee (void) { 
int nLocall; 
static int nLocal2; 
// 
// Do work here. 
// 
return nLocall; 


} 


Now WorkerBee doesn’t have access to any persistent memory that’s local to a thread. 
nLocali1 is persistent only for the life of a single call to WorkerBee. nLocal2 is persis- 
tent across calls to WorkerBee but is static and therefore shared among all threads 
calling WorkerBee. One solution would be to have ThreadProc pass a pointer to a 
stack-based variable to WorkerBee. This strategy works, but only if you have control 
over the routines calling WorkerBee. What if you’re writing a DLL and you need to 
have a routine in the DLL maintain a different state for each thread calling the rou- 
tine? You can’t define static variables in the DLL because they would be shared across 
the different threads. You can’t define local variables because they aren’t persistent 
across calls to your routine. The answer is to use thread local storage. 

Thread local storage allows a process to have its own cache of values that are 
guaranteed to be unique for each thread in a process. This cache of values is small 
because an array must be created for every thread created in the process, but it’s large 
enough, if used intelligently. To be specific, the system constant, TLS_MINIMUM_ 
AVAILABLE, is defined to be the number of slots in the TLS array that’s available for 
each process. For Windows CE, like Windows NT, this value is defined as 64. So, each 
process can have 64 4-byte values that are unique for each thread in that process. 
For the best results, of course, you must manage those 64 slots well. 

To reserve one of the TLS slots, a process calls 


DWORD TlsAlloc (void); 


TlsAlloc looks through the array to find a free slot in the TLS array, marks it as in use, 
and then returns an index value to the newly assigned slot. If no slots are available, 
the function returns -1. It’s important to understand that the individual threads don’t 
call TisAlloc. Instead, the process or DLL calls it before creating the threads that will 
use the TLS slot. 

Once a slot has been assigned, each thread can access its unique data in the 
slot by calling this function: 


BOOL TlsSetValue (DWORD dwTlsIndex, LPVOID IpTlsValue); 
and 


LPVOID TlsGetValue (DWORD dwTlsIndex); 
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For both of these functions, the TLS index value returned by 7/sAlloc specifies 
the slot that contains the data. Both 7isGetValue and TlsSetValue type the data as a 
PVOID, but the value can be used for any purpose. The advantage of thinking of the 
TLS value as a pointer is that a thread can allocate a block of memory on the heap, 
and then keep the pointer to that data in the TLS value. This allows each thread to 
maintain a block of thread-unique data of almost any size. 

One other matter is important to thread local storage. When TisAlloc reserves a 
slot, it zeros the value in that slot for all currently running threads. All new threads are 
created with their TLS array initialized to 0 as well. This means that a thread can safely 
assume that the value in its slot will be initialized to 0. This is helpful for determining 
whether a thread needs to allocate a memory block the first time the routine is called. 

When a process no longer needs the TLS slot, it should call this function: 


BOOL TlsFree (DWORD dwTlsIndex); 


The function is passed the index value of the slot to be freed. The function re- 
turns TRUE if successful. This function frees only the TLS slot. If threads have allo- 
cated storage in the heap and stored pointers to those blocks in their TLS slots, that 
storage isn’t freed by this function. Threads are responsible for freeing their own 
memory blocks. 


SYNCHRONIZATION 


With multiple threads running around the system, you need to coordinate the activi- 
ties. Fortunately, Windows CE supports almost the entire extensive set of standard 
Win32 synchronization objects. The concept of synchronization objects is fairly simple. 
A thread waits on a synchronization object. When the object is signaled, the waiting 
thread is unblocked and is scheduled (according to the rules governing the thread’s 
priority) to run. 

Windows CE doesn’t support some of the synchronization primitives supported 
by Windows NT. These unsupported elements include semaphores, file change no- 
tifications, and waitable timers. Support for semaphores is planed for Windows CE in 
the near future. The lack of waitable timer support can easily be worked around us- 
ing the more flexible Notification API, unique to Windows CE. 

One aspect of Windows CE unique to it is that the different synchronization ob- 
jects don’t. share the same namespace. This means that if you have an event named 
Bob, you can also have a mutex named Bob. (I'll talk about mutexes later in this chap- 
ter.) This naming convention is different from Windows NT’s rule, where all kernel objects 
(of which synchronization objects are a part) share the same namespace. While having 
the same names in Windows CE is possible, it’s not advisable. Not only does the prac- 
tice make your code incompatible with Windows NT, there’s no telling whether a re- 
design of the internals of Windows CE might just enforce this restriction in the future. 
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The first synchronization primitive I’ll describe is the event object. An event object is 
a synchronization object that can be in a signaled or nonsignaled state. Events are 
useful to a thread to let it be known that, well, an event has occurred. Event objects 
can either be created to automatically reset from a signaled state to a nonsignaled 
state or require a manual reset to return the object to its nonsignaled state. Starting 
with Windows CE 2.0, events can be named and therefore shared across different pro- 
cesses allowing interprocess synchronization. 
An event is created by means of this function: 


HANDLE CreateEvent (LPSECURITY_ATTRIBUTES IpEventAttributes, 
BOOL bManualReset, BOOL bInitialState, 
LPTSTR 1pName) ; 


As with all calls in Windows CE, the security attributes parameter, IpEventAttributes, 
should be set to NULL. The second parameter indicates whether the event being cre- 
ated requires a manual reset or will automatically reset to a nonsignaled state imme- 
diately after being signaled. Setting bManualReset to TRUE creates an event that must 
be manually reset. The binitialState parameter specifies whether the event object is 
initially created in the signaled or nonsignaled state. Finally, the jpName parameter 
points to an optional string that names the event. Events that are named can be shared 
across processes. If two processes create event objects of the same name, the pro- 
cesses actually share the same object. This allows one process to signal the other 
process using event objects. If you don’t want a named event, the Jponame parameter 
can be set to NULL. 

To share an event object across processes, each process must individually cre- 
ate the event object. You can’t simply create the event in one process and send the 
handle of that event to another process. To determine whether a call to CreateEvent 
created a new event object or opened an already created object, you can call Get- 
LastError immediately following the call to CreateEvent. If GetLastError returns 
ERROR_ALREADY_EXISTS, the call opened an existing event. 

Once you have an event object, you’ll need to be able to signal the event. You 
accomplish this using either of the following two functions: 


BOOL SetEvent (HANDLE hEvent); 
or 
BOOL PulseEvent (HANDLE hEvent); 


The difference between these two functions is that SetEvent doesn’t automatically reset 
the event object to a nonsignaled state. For autoreset events, SetEvent is all you need 
because the event is automatically reset once a thread unblocks on the event. For 
manual reset events, you must manually reset the event with this function: 


BOOL ResetEvent (HANDLE hEvent); 
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These event functions sound like they overlap, so let’s review. An event ob- 
ject can be created to reset itself or require a manual reset. If it can reset itself, a 
call to SetEvent signals the event object. The event is then automatically reset to the 
nonsignaled state when one thread is unblocked after waiting on that event. An event 
that resets itself doesn’t need PulseEvent or ResetEvent. If, however, the event object 
was created requiring a manual reset, the need for ResetEvent is obvious. 

PulseEvent signals the event and then resets the event, which allows ai/ threads 
waiting on that event to be unblocked. So, the difference between PulseEvent on a 
manually resetting event and SetEvent on an automatic resetting event is that using 
SetEvent on an automatic resetting event frees only one thread to run even if many 
threads are waiting on that event. PulseEvent frees all threads waiting on that event. 

You destroy event objects by calling CloseHandle. If the event object is named, 
Windows maintains a use count on the object so one call to CloseHandle must be 
made for every call to CreateEvent. 


Waiting... 


It’s all well and good to have event objects; the question is how to use them. Threads 
wait on events, as well as on the soon to be described mutex, using one of the fol- 
lowing functions: WaitForSingleObject, WaitForMultipleObjects, Msg WaitForMultiple- 
Objects, or Msg WaitForMultipleObjectsEx. Under Windows CE, the WaitForMultiple 
functions are limited in that they can’t wait for all objects of a set of objects to be 
signaled. These functions support waiting for one object in a set of objects being sig- 
naled. Whatever the limitations of waiting, I can’t emphasize enough that waiting is 
good. While a thread is blocked with one of these functions, the thread enters an 
extremely efficient state that takes very littke CPU processing power and battery power. 

Another point to remember is that the thread responsible for handling a mes- 
sage loop in your application (usually the application’s primary thread) shouldn’t be 
blocked by WaitForSingleObject or WaitForMultipleObjects because the thread can’t 
be retrieving and dispatching messages in the message loop if it’s blocked waiting 
on an object. The function Msg WaitForMultipleObjects gives you a way around this 
problem, but in a multithreaded environment, it’s usually easier to let the primary 
thread handle the message loop and secondary threads handle the shared resources 
that require blocking on events. 


Waiting on a single object 
A thread can wait on a synchronization object with the function: 
DWORD WaitForSingleObject (HANDLE hHandle, DWORD dwMilliseconds); 


The function takes two parameters: the handle to the object being waited on and a 
timeout value. If you don’t want the wait to time out, you can pass the value INFI- 
NITE in the dwMilliseconds parameter. The function returns a value that indicates why 
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the function returned. Calling WaitForSingleObject blocks the thread until the event 
is signaled, the synchronization object is abandoned, or the timeout value is reached. 
WaitForSingleObject returns one of the following values: 


4] WAIT_OBJECT_O The specified object was signaled. 


M £WAIT_TIMEOUT The timeout interval elapsed, and the object’s state re- 
mains nonsignaled. 


fy WAIT_ABANDONED _ The thread that owned a mutex object being waited 
on ended without freeing the object. | 


M WAIT_FAILED The handle of the synchronization object was invalid. 


You must check the return code from WaitForSingleObject to determine whether 
the event was signaled or simply that the time out had expired. (The WAIT_ABAN- 
DONED return value will be relevant when I talk about mutexes soon.) 


Waiting on processes and threads 
I’ve talked about waiting on events, but you can also wait on handles to processes 
and threads. These handles are signaled when their processes or threads terminate. 
This allows a process to monitor another process (or thread) and perform some ac- 
tion when the process terminates. One common use for this feature is for one pro- 
cess to launch another, and then by blocking on the handle to the newly created 
process, wait until that process terminates. 

The rather irritating routine below is a thread that demonstrates this technique 
by launching an application, blocking until that application closes, and then relaunch- 
ing the application: 


DWORD WINAPI KeepRunning (PVOID pArg) { 
PROCESS_INFORMATION pi; 
TCHAR szFileName[LMAX_PATH]; 
INT re = @; 


// Copy the filename. 
Lstrcpy (szFileName, (LPTSTR)pArg); 
while (1) { 
// Launch the application. 
re = CreateProcess (szFileName, NULL, NULL, NULL, FALSE, 
@, NULL, NULL, NULL, &pi); 
// If the application didn't start, terminate thread. 
if (!rc) 
return -1; 
// Close the new process's primary thread handle. 
CloseHandle (pi.hThread) ; 
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// Wait for user to close the application. 
rc = WaitForSingleObject (pi.hProcess, INFINITE); 


// Close the old process handle. 
CloseHandle (pi.hProcess); 


// Make sure we returned from the wait correctly. 
if (re != WAIT_OBJECT_®) 
return -2; 


} 


return @; //This should never get executed. 


This code simply launches the application using CreateProcess and waits on the 
process handle returned in the PROCESS_INFORMATION structure. Notice that the 
thread closes the child process’s primary thread handle and, after the wait, the handle 
to the child process itself. 


Waiting on multiple objects 

A thread can also wait on a number of events. The wait can end when any one of the 
events is signaled. The function that enables a thread to wait on multiple objects is 
this one: 


DWORD WaitForMultipleObjects (DWORD nCount, CONST HANDLE *1]pHandles, 
BOOL bWaitAll1, DWORD dwMilliseconds); 


The first two parameters are a count of the number of events or mutexes to wait on 
and a pointer to an array of handles to these events. The bWaitAll parameter must be 
set to FALSE to indicate the function should return if any of the events are signaled. 
The final parameter is a timeout value, in milliseconds. As with WaitForSingleObject, 
passing INFINITE in the timeout parameter disables the time out. Windows CE doesn’t 
support the use of WaitForMultipleObjects to enable waiting for all events in the ar- 
ray to be signaled before returning. 

Like WaitForSingleObject, WaitForMultipleObjects returns a code that indicates 
why the function returned. If the function returned due to a synchronization object 
being signaled, the return value will be WAIT_OBJECT_0 plus an index into the handle 
array that was passed in the /pHandles parameter. For example, if the first handle in 
the array unblocked the thread, the return code would be WAIT_OBJECT_0; if the 
second handle was the cause, the return code would be WAIT_OBJECT_0 + 1. The 
other return codes used by WaitForSingleObject—WAIT_TIMEOUT, WAIT_ABAN- 
DONED, and WAIT_FAILED—are also returned by WaitForMultipleObjects for the 
same reasons. 
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Waiting while dealing with messages 

The Win32 API provides other functions that allow you to wait on a set of objects as 
well as messages: these are Msg WaitForMultipleObjects and Msg WaitForMultiple- 
ObjectsEx. Under Windows CE, these functions act identically, so I'll describe only 
Msg WaitForMultipleObjects. This function essentially combines the wait function, 
Msg WaitForMultipleObjects, with an additional check into the message queue so that 
the function returns if any of the selected categories of messages are received during 
the wait. The prototype for this function is the following: 


DWORD MsgWaitForMultipleObjectsEx (DWORD nCount, LPHANDLE pHandles, 
BOOL fWaitAll, DWORD dwMilliseconds, 
DWORD dwWakeMasks); 


This function has a number of limitations under Windows CE. As with WaitFor- 
MultipleObjects, Msg WaitForMultipleObjectsEx can’t wait for all objects to be signaled. 
Nor are all the dwWakeMask flags supported by Windows CE. Windows CE supports 
the following flags in dwWakeMask. Each flag indicates a category of messages that, 
when received in the message queue of the thread, causes the function to return. 


M OS_ALLINPUT Any message has been received. 


QS_INPUT An input message has been received. 


M OS_KEY A key up, key down, or syskey up or down message has been 
received. 


QS_ MOUSE A mouse move or mouse click message has been received. 
OS_MOUSEBUTTON A mouse click message has been received. 
OS_MOUSEMOVE A mouse move message has been received. 
OQS_PAINT A WM_PAINT message has been received. 


QS_POSTMESSAGE A posted message, other than those in this list, has 
been received. 


M OS_SENDMESSAGE A sent message, other than those in this list, has been 
received. 


M@ OS_TIMER A WM_TIMER message has been received. 


The function is used inside the message loop, so that an action or actions can 
take place in response to the signaling of a synchronization object while your pro- 
gram is still processing messages. 

The return value is WAIT_OBJECT_0 up to WAIT_OBJECT_0 + nCount - 1 for 
the objects in the handle array. If a message causes the function to return, the return 
value is WAIT_OBJECT_0 + nCount. An example of how this function might be used 
follows. In this code, the handle array has only one entry, bSyncHandle. 
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fContinue = TRUE; 
while (fContinue) { 
rc = MsgWaitForMultipleObjects (1, &hSyncHandle, FALSE, 
INFINITE, QS_ALLINPUT); 
if (rc == WAIT_OBJECT_®@) { 


// 
// Do work as a result of sync object. 
// 

} else if (rc == WAIT_OBJECT_O + 1) { 


// It's a message, process it. 
PeekMessage (&msg, hWnd, @, @, PM_REMOVE); 
if (msg.message == WM_QUIT) 
fContinue = FALSE; 
else { 
TranslateMessage (&msg); 
DispatchMessage (&msg); 


Mutexes 


Earlier I described the event object. That object resides in either a signaled or non- 
signaled state. Another synchronization object is the mutex. A mutex is a synchroni- 
zation object that’s signaled when it’s not owned by a thread and nonsignaled when 
it is owned. Mutexes are extremely useful for coordinating exclusive access to a re- 
source such as a block of memory across multiple threads. 

A thread gains ownership by waiting on that mutex with one of the wait func- 
tions. When no other threads own the mutex, the thread waiting on the mutex is 
unblocked, and implicitly gains ownership of the mutex. After the thread has com- 
pleted the work that requires ownership of the mutex, the thread must explicitly re- 
lease the mutex with a call to ReleaseMutex. 

To create a mutex, call this function: 


HANDLE CreateMutex (LPSECURITY_ATTRIBUTES lpMutexAttributes, 
BOOL bInitialOwner, LPCTSTR IpName); 


The pMutexAttributes parameter should be set to NULL. The binitialOwner parame- 
ter lets you specify that the calling thread should immediately own the mutex being 
created. Finally, the JoName parameter lets you specify a name for the object so that 
it can be shared across other processes. When calling CreateMutex with a name speci- 
fied in the /pName parameter, Windows CE checks whether a mutex with the same 
name has already been created. If so, a handle to the previously created mutex is 
returned. To determine whether the mutex already exists, call GetLastError. It returns 
ERROR_ALREADY_EXISTS if the mutex has been previously created. 
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Gaining immediate ownership of a mutex using the binitialOwner parameter 
works only if the mutex is being created. Ownership isn’t granted if you’re opening 
a previously created mutex. If you need ownership of a mutex, be sure to call GetLast- 
Error to determine whether the mutex had been previously committed. If so, call 
WaitForSingleObject to gain ownership of the mutex. 

You release the mutex with this function: 


BOOL ReleaseMutex (HANDLE hMutex); 


The only parameter is the handle to the mutex. 

If a thread owns a mutex and calls one of the wait functions to wait on that 
same mutex, the wait call immediately returns because the thread already owns the 
mutex. Since mutexes retain an ownership count for the number of times the wait 
functions are called, a call to ReleaseMutex must be made for each nested call to the 
wait function. 


Critical Sections 
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Using critical sections is another method of thread synchronization. Critical sections 
are good for protecting sections of code from being executed by two different threads 
at the same time. Critical sections work by having a thread call EnterCriticalSection 
to indicate that it has entered a critical section of code. If another thread calls 
EnterCriticalSection referencing the same critical section object, it’s blocked until the 
first thread makes a call to LeaveCriticalSection. Critical sections can protect more than 
one linear section of code. All that’s required is that all sections of code that need to 
be protected use the same critical section object. The one limitation of critical sec- 
tions is that they can be used to coordinate threads only within a process. 

To use a critical section, you first create a critical section handle with this function: 


void InitializeCriticalSection (LPCRITICAL_SECTION IpCriticalSection); 


The only parameter is a pointer to a CRITICAL_SECTION structure that you define 
somewhere in your application. Be sure not to allocate this structure on the stack of 
a function that will be deallocated as soon the function returns. You should also not 
move or copy the critical section structure. Since the other critical section functions 
require a pointer to this structure, you’ll need to allocate it within the scope of all 
functions using the critical section. While the CRITICAL_SECTION structure is defined 
in WINBASE.H, an application doesn’t need to manipulate any of the fields in that 
structure. So, for all practical purposes, think of a pointer to a CRITICAL_SECTION 
structure as a handle, instead of as a pointer to a structure of a known format. 

When a thread needs to enter a protected section of code, it should call this 
function: | 


void EnterCriticalSection (LPCRITICAL_SECTION 1pCriticalSection); 
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The function takes as its only parameter a pointer to the critical section structure ini- 
tialized with InitializeCriticalSection. If the critical section is already owned by an- 
other thread, this function blocks the new thread and doesn’t return until the other 
thread releases the critical section. If the thread calling EnterCriticalSection already 
owns the critical section, then a use count is incremented and the function returns 
immediately. 

When a thread leaves a critical section, it should call this function: 


void LeaveCriticalSection (LPCRITICAL_SECTION lpCriticalSection) ; 


As with all the critical section functions, the only parameter is the pointer to the criti- 
cal section structure. Since critical sections track a use count, one call to Leave- 
CriticalSection must be made for each call to EnterCriticalSection by the thread that 
owns the section. | 

Finally, when you’re finished with the critical section, you should call 


void DeleteCriticalSection (LPCRITICAL_SECTION 1lpCriticalSection); 


This cleans up any system resources used to manage the critical section. 


interlocked Variable Access 


Here’s one more low-level method for synchronizing threads—using the functions 
for interlocked access to variables. While programmers with multithread experience 
already know this, I need to warn you that Murphy’s Law! seems to come into its 
own when you’re using multiple threads in a program. One of the sometimes over- 
looked issues in a preemptive multitasking system is that a thread can be preempted 
in the middle of incrementing or checking a variable. For example, a simple code 
fragment such as 
if (!it++) { 

// Do something because i was zero. 
} 


can cause a great deal of trouble. To understand why, let’s look into how that state- 
ment might be compiled. The assembly code for that if statement might look some- 
thing like this: 


load regl, [addr of i] ;Read variable 

add reg2, regl, 1 sreg2 = regl + 1 
store reg2, Laddr of i] — ;Save incremented var 
bne regl, zero, skipblk ;Branch regl != zero 


There’s no reason that the thread executing this section of code couldn’t be preempted 
by another thread after the load instruction and before the store instruction. If this 


1. Murphy’s Law: Anything that can go wrong will go wrong. Murphy’s first corollary: When some- 
thing goes wrong, it happens at the worst possible moment. 
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happened, two threads could enter the block of code when that isn’t the way the code 
is supposed to work. Of course, I’ve already described a number of methods (such 
as critical sections and the like) that you can use to prevent such incidents from 
occurring. But for something like this, a critical section is overkill. What you need is 
something lighter. 

Windows CE supports three of the interlocked functions from the Win32 API; 
InterlockedIncriment, InterlockedDecriment, and InterlockedExchange. Each of these 
allows a thread to increment, decrement, and exchange a variable without your hav- 
ing to worry about the thread being preempted in the middle of the operation. The 
functions are prototyped here: 


LONG InterlockedIncrement(LPLONG 1pAddend) ; 
LONG InterlockedDecrement(LPLONG 1pAddend) ; 


LONG InterlockedExchange(LPLONG Target, LONG Value); 


For the interlocked increment and decrement, the one parameter is a pointer to the 
variable to increment or decrement. The returned value is the new value of the vari- 
able after it has been incremented or decremented. The InterlockedExchange func- 
tion takes a pointer to the target variable and the new value for the variable. It returns 
the previous value of the variable. Rewriting the previous code fragment so that it’s 
thread safe produces this code: 


if (!InterlockedIncrement(&i)) { 
// Do something because i was zero. 


} 


INTERPROCESS COMMUNICATION 


There are many cases where two Windows CE processes need to communicate. The 
walls between processes that protect processes from one another prevent casual 
exchanging of data. The memory space of one process isn’t exposed to another pro- 
cess. Handles to files or other objects can’t be passed from one process to another. 
Windows CE doesn’t support the DuplicateHandle function available under Win- 
dows NT, which allows one process to open a handle used by another process. Nor, 
as I mentioned before, does Windows CE support handle inheritance. Some of the 
other more common methods of interprocess communication, such as named pipes, 
are also not supported under Windows CE. However, you can choose from plenty of 
ways to enable two or more processes to exchange data. 


Finding Other Processes 


Before you can communicate with another process, you have to determine whether 
it’s running on the system. Strategies for finding whether another process is running 
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depend mainly on whether you have control of the other process. If the process to 
be found is a third-party application in which you have no control over the design of 
the other process, the best method might be to use FindWindow to locate the other 
process’s main window. FindWindow can search either by window class or by win- 
dow title. You can also enumerate the top-level windows in the system using Enum- 
Windows. You can also use the ToolHelp debugging functions to enumerate the 
processes running, but this works only when the ToolHelp DLL is loaded on the sys- 
tem and unfortunately, it generally isn’t included, by default, on most systems. 

If you’re writing both processes, however, it’s much easier to enumerate them. 
In this case, the best methods include using the tools you'll later use in one process 
to communicate with the other process, such as named mutexes, events, or memory- 
mapped objects. When you create one of these objects, you can determine whether 
you're the first to create the object or you’re simply opening another object by call- 
ing GetLastError after another call created the object. And the simplest method might 
be the best; call FindWindow and send a WM_USER message to the main window of 
the other process. 


WM_COPYDATA 

Once you’ve found your target process, the talking can begin. If you’re staying at the 
window level, a simple method of communicating is to send a WM_COPYDATA 
message. WM_COPYDATA is unique in that it’s designed to send blocks of data from 
one process to another. You can’t use a standard, user-defined message to pass pointers 
to data from one process to another because a pointer isn’t valid across processes. 
WM_COPYDATA gets around this problem by having the system translate the pointer 
to a block of data from one process’s address space to another’s. The recipient pro- 
cess is required to copy the data immediately into its own memory space, but this 
message does provide a quick and dirty method of sending blocks of data from one 
process to another. 


Named memory-mapped objects 
The problem with WM_COPYDATA is that it can be used only to copy fixed blocks 
of data at a specific time. Using a named memory-mapped object, two processes can 
allocate a shared block of memory that’s equally accessible to both processes at the 
same time. You should use named memory-mapped objects so that the system can 
maintain a proper use count on the object. This procedure prevents one process from 
freeing the block when it terminates while the other process is still using the block. 
Of course, this level of interaction comes with a price. You need some synchro- 
nization between the processes when they’re reading and writing data in the shared 
memory block. The use of named mutexes and named events allows processes to 
coordinate their actions. Using these synchronization objects requires the use of sec- 
ondary threads so that the message loop can be serviced, but this isn’t an exceptional 
burden. 
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I described how to create memory-mapped objects in Chapter 6. The example 
program that shortly follows uses memory-mapped objects and synchronization 
objects to coordinate access to the shared block of memory. 


Communicating with files and databases 

A more basic method of interprocess communication is the use of files or a custom 
database. These methods provide a robust, if slower, communication path. Slow is 
relative. Files and databases in the Windows CE object store are slow in the sense 
that the system calls to access these objects must find the data in the object store, 
uncompress the data, and deliver it to the process. However, since the object store is 
based in RAM, you see none of the extreme slowness of a mechanical hard disk that 
you’d see under Windows NT or Windows 98. 


The XTalk Example Program 


The following example program, XTalk, uses events, mutexes, and a shared memory- 
mapped block of memory to communicate among different copies of itself. The ex- 
ample demonstrates the rather common problem of one-to-many communication. In 
this case, the XTalk window has an edit box with a Send button next to it. When a 
user taps the Send button, the text in the edit box is communicated to every copy of 
XTalk running on the system. Each copy of XTalk receives the text from the sending 
copy and places it in a list box also in the XTalk window. Figure 8-1 shows two XTalk 


programs communicating. 
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Figure 8-1. 
The desktop showing two XTalk windows. 
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Figure 8-2. The source code for XTalk. 
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The interesting routines in the XTalk example are the InitInstance procedure 
and the two thread procedures SenderThread and ReaderTbread. The relevant part 
of InitInstance is shown below with the error checking code removed for brevity. 


// Create mutex used to share memory-mapped structure. 


g_hmWriteOkay = CreateMutex (NULL, TRUE, TEXT ("XTALKWRT")); 
re = GetLastError(); 


fFirstApp = FALSE; 


// Wait here for ownership to insure the initialization is done. 
// This is necessary since CreateMutex doesn't wait. 
re = WaitForSingleObject (g_hmWriteOkay, 2000); 
if (re != WAIT_OBJECT_®Q) 
return @; 


// Create a file-mapping object. 


g_hMMObj = CreateFileMapping ((HANDLE)-1, NULL, PAGE_READWRITE, @, 
MMBUFFSIZE, TEXT ("XTALKBLK")); 


// Map into memory the file-mapping object. 
g_pBuff = (PSHAREBUFF)MapViewOfFile (g_hMMObj, FILE_MAP_WRITE, 
@, 0, 0); 


// Initialize structure if first application started. 
if (fFirstApp) 


memset (g_pBuff, @, sizeof (SHAREBUFF)); 
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// Increment app running count. Interlock not needed due to mutex. 
g_pBuff->nAppCnt++; 


// Release the mutex. We need to release the mutex twice 
// if we owned it when we entered the wait above. 
ReleaseMutex (g_hmWriteOkay); 
if (fFirstApp) 

ReleaseMutex (g_hmWriteOkay); 


// Now create events for read and send notification. 
g_hSendEvent = CreateEvent (NULL, FALSE, FALSE, NULL); 
g_hReadEvent = CreateEvent (NULL, TRUE, FALSE, TEXT ("XTALKREAD")); 
g_hReadDoneEvent = CreateEvent (NULL, FALSE, FALSE, 
TEXT ("XTALKDONE"™)); 


This code is responsible for creating the necessary synchronization objects as 
well as creating and initializing the shared memory block. The mutex object is cre- 
ated first with the parameters set to request initial ownership of the mutex object. A 
call is then made to GetLastError to determine whether the mutex object has already 
been created. If not, the application assumes the first instance of XTalk is running 
and later will initialize the shared memory block. Once the mutex is created, an ad- 
ditional call is made to WaitForSingleObject to wait until the mutex is released. This 
call is necessary to prevent a late starting instance of XTalk from disturbing commu- 
nication in progress. Once the mutex is owned, calls are made to CreateFileMapping 
and MapViewOfFile to create a named memory-mapped object. Since the object is 
named, each process that opens the object opens the same object and is returned a 
pointer to the same block of memory. 

Once the shared memory block is created, the first instance of XTalk zeros out 
the block. This procedure also forces the block of RAM to be committed because 
memory-mapped objects by default are autocommit blocks. Then nAppCnt, which 
keeps a count of the running instances of XTalk, is incremented. Finally the mutex 
protecting the shared memory is released. If this is the first instance of XTalk, Release- 
Mutex must be called twice because it gains ownership of the mutex twice—once 
when the mutex is created and again when the call to WaitForSingleObject is made. 

Finally, three event objects are created. SendEvent is an unnamed event, local 
to each instance of XTalk. The primary thread uses this event to signal the sender 
thread that the user has pressed the Send button and wants the text in the edit box 
transmitted. The ReadEvent is a named event that tells the other instances of XTalk 
that there’s data to be read in the transfer buffer. The ReadDoneEvent is a named event 
signaled by each of the receiving copies of XTalk to indicate that they have read 
the data. 
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The two threads, ReaderThread and SenderTbread are created immediately after 
the main window of XTalk is created. The code for SenderThread is shown here: 


int SenderThread (PVOID pArg) { 
HWND hWnd; 
INT nGoCode, rc; 
TCHAR szText[TEXTSIZE]; 


hWnd = (HWND)pArg; 
while (1) { 
nGoCode = WaitForSingleObject (g_hSendEvent, INFINITE); 
if (nGoCode == WAIT_OBJECT_®@) { 
SendDlgItemMessage (hWnd, IDD_OUTTEXT, WM_GETTEXT, 
sizeof (szText), (LPARAM)szText); 


re = WaitForSingleObject (g_hmWriteOkay, 2000); 
if (rc == WAIT_OBJECT_®@) { 
Istrcpy (g_pBuff->szText, szText); 
g_pBuff->nReadCnt = g_pBuff->nAppCnt; 
PulseEvent (g_hReadEvent); 


// Wait while reader threads get data. 
while (g_pBuff->nReadCnt ) 
re = WaitForSingleObject (g_hReadDoneEvent, 
INFINITE); 
ReleaseMutex (g_hmWriteOkay); 


} 
} 
return @; 
} X 


The routine waits on the primary thread of XTalk to signal SendEvent. The pri- 
mary thread of XTalk makes the signal in response to a WM_COMMAND message 
from the Send button. The thread is then unblocked, reads the text from the edit control, 
and waits to gain ownership of the WriteOkay mutex. This mutex protects two cop- 
ies of XTalk from writing to the shared block at the same time. When the thread owns 
the mutex, it writes the string read from the edit control into the shared buffer. It then 
copies the number of active copies of XTalk into the nReadCnt variable in the same 
shared buffer, and pulses the ReadEvent to tell the other copies of XTalk to read the 
newly written data. A manual resetting event is used so that all threads waiting on 
the event will be unblocked when the event is signaled. 

The thread then waits for the nReadCnt variable to return to 0. Each time a reader 
thread reads the data, the nReadCnt variable is decremented and the ReadDone 
event signaled. Note that the thread doesn’t spin on this variable but uses an event to 
tell it when to check the variable again. This would actually be a great place to use 
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WaitForMultipleObjects and have all reader threads signal when they’ve read the data, 
but Windows CE doesn’t support the WaitAll flag in WaitForMultipleObjects. 
Finally, when all the reader threads have read the data, the sender thread re- 
leases the mutex protecting the shared segment and the thread returns to wait for 
another send event. 
The ReaderThread routine is even simpler. Here it is: 


int ReaderThread (PVOID pArg) { 
HWND hWnd; 
INT nGoCode, rc, i; 
TCHAR szText[TEXTSIZE]; 


hWnd = (HWND)pArg; 
while (1) { 
nGoCode = WaitForSingleObject (g_hReadEvent, INFINITE); 
if (nGoCode == WAIT_OBJECT_®) { 
j = SendDigItemMessage (hWnd, IDD_INTEXT, LB_ADDSTRING, @, 
(LPARAM) g_pBuff->szText) ; 
SendDilgItemMessage (hWnd, IDD_INTEXT, LB_SETTOPINDEX, i, @); 


InterlockedDecrement (&g_pBuff->nReadCnt ); 
SetEvent (g_hReadDoneEvent) ; 
} 


} 
return Q; 


The reader thread starts up and immediately blocks on ReadEvent. When it’s 
unblocked, it adds the text from the shared buffer into the list box in its window. The 
list box is then scrolled to show the new line. After this is accomplished, the nReadCnt 
variable is decremented using InterlockedDecrement to be thread safe, and the Read- 
Done event is signaled to tell the SenderThread to check the read count. After that’s 
accomplished, the routine loops around and waits for another read event to occur. 


EXCEPTION HANDLING 


Windows CE, along with Visual C++ for Windows CE, supports Microsoft’s standard, 
structured exception handling extensions to the C language, the __try, __except and 
__try, __ finally blocks. Note that Visual C++ for Windows CE doesn’t support the 
full C++ exception handling framework with keywords such as catch and throw. 
Windows exception handling is complex and if I were to cover it completely, 
I could easily write another entire chapter. The following review introduces the con- 
cepts to non-Win32 programmers and conveys enough information about the sub- 
ject for you to get your feet wet. If you want to wade all the way in, the best source 
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for a complete explanation of Win32 exception handling is Jeffrey Richter’s Advanced 
Windows third edition (Microsoft Press, 1997). 


The __try, __except Block 
The first construct Pll talk about is the __try, __ except block which looks like this: 


__try { 
// Try some code here that might cause an exception. 


} 
__except (exception filter) { 


// This code is depending on the filter on the except line. 


Essentially, the try-except pair allows you the ability to anticipate exceptions 
and handle them locally instead of having Windows terminate the thread or the pro- 
cess because of an unhandled exception. 

The exception filter is essentially a return code that tells Windows how to handle 
the exception. You can hard code one of the three possible values or call a function 
that dynamically decides how to respond to the exception. 

If the filter returns EXCEPTION_EXECUTE_HANDLER, Windows aborts the 
execution in the try block and jumps to the first statement in the except block. This is 
helpful if you’re expecting the exception and you know how to handle it. In the code 
that follows, the access to memory is protected by a __try, __ except block. 


BYTE ReadByteFromMemory (LPBYTE pPtr, BOOL *bDataValid) { 
BYTE ucData = Q; 


*bDataValid = TRUE; 

autry: 4 
ucData = *pPtr; 

} 

__except (DecideHowToHandleException ()) { 
// The pointer isn't valid, clean up. 
ucData = Q@; 

*bDataValid = FALSE; 

} 


return ucData;: 


int DecideHowToHandleException (void) { 
return EXCEPTION_EXECUTE_HANDLER; 
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If the memory read line above wasn’t protected by a __try, __ except block and 
an invalid pointer was passed to the routine, the exception generated would have 
been passed up to the system, causing the thread and perhaps the process to be ter- 
minated. If you use the __try, __ except block, the exception is handled locally and 
the process continues with the error handled locally. 

Another possibility is to have the system retry the instruction that caused the 
exception. You can do this by having the filter return EXCEPTION_CONTINUE_ 
EXECUTION. On the surface, this sounds like a great option—simply fix the prob- 
lem and retry the operation your program was performing. The problem with this 
approach is that what will be retried isn’t the /ine that caused the exception, but the 
machine instruction that caused the exception. The difference is illustrated by the 
following code fragment that looks okay but probably won’t work: 


// An example that doesn't work... 
int DivideIt (int aVal, int bVal) { 


int cVal; 

__try { 
cVal = aVal / DVal; 

} 

__except (EXCEPTION_CONTINUE_EXECUTION) { 
bVal = 1; 

} 


return cVal; 


The idea in this code is noble; protect the program from a divide-by-zero error 
by ensuring that if the error occurs, the error is corrected by replacing bVal with 1. 
The problem is that the line 


cVal = aVal / bVal: 


is probably compiled to something like the following on a MIPS-compatible CPU: 


lw t6,aVal(sp) sLoad aVal 

lw t7,bVal(sp) ;Load bVal 

div t6,t7 ;Perform the divide 
SW t6,cVal(sp) ;Save result into cVal 


In this case, the third instruction, the div, causes the exception. Restarting the 
code after the exception results in the restart beginning with the div instruction. The 
problem is that the execution needs to start at least one instruction earlier to load the 
new value from bVal into the register. The moral of the story is that attempting to 
restart code at the point of an exception is risky at best and at worst, unpredictable. 

The third option for the exception filter is to not even attempt to solve the prob- 
lem and to pass the exception up to the next, higher __try, __ except block in code. 
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This is accomplished by the exception filter returning EXCEPTION_CONTINUE_ 
SEARCH. Since __ try, __ except blocks can be nested, it’s good practice to handle spe- 
cific problems in a lower, nested __try, __except block and more global errors at a 
higher level. 


Determining the problem 
With these three options available, it would be nice if Windows let you in on why 
the exception occurred. Fortunately, Windows provides the function 


DWORD GetExceptionCode (void); 


This function returns a code that indicates why the exception occurred in the first 
place. The codes are defined in WINBASE.H and range from EXCEPTION_ACCESS _ 
VIOLATION to CONTROL_C_EXIT, with a number of codes in between. Another 
function allows even more information: 


LPEXCEPTION_POINTERS GetExceptionInformation (void); 


GetExceptionInformation returns a pointer to a structure that contains pointers 
to two structures: EXCEPTION RECORD and CONTEXT. EXCEPTION_RECORD is 
defined as 


typedef struct _EXCEPTION_RECORD { 

DWORD ExceptionCode; 

DWORD ExceptionFlags; 

struct _EXCEPTION_RECORD *ExceptionRecord; 

PVOID ExceptionAddress; 

DWORD NumberParameters; 

DWORD ExceptionInformation[EXCEPTION_MAXIMUM_PARAMETERS]; 
} EXCEPTION_RECORD; 


The fields in this structure go into explicit detail about why an exception oc- 
curred. To narrow the problem down even further, you can use the CONTEXT struc- 
ture. The CONTEXT structure is different for each CPU and essentially defines the 
exact state of the CPU when the exception occurred. 

There are limitations on when these two exception information functions can 
be called. GetExecptionCode can only be called from inside an except block or from 
within the exception filter function. The GetExceptionInformation function can be 
called only from within the exception filter function. 


The __try, __ finally Block 
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__try, __ finally block. It looks like this: 
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= try < 
// Do something here. 


} 
“__ finally { 


// This code is executed regardless of what happens in the try block. 


The goal of the __try, __ finally block is to provide a block of code, the finally 
block, that always executes regardless of how the other code in the try block attempts 
to leave the block. If there’s no return, break or goto in the try block, the code in the 
finally block executes immediately following the last statement in the try block. If 
the try block has a return or a goto or some other statement that transfers execution 
out of the try block, the compiler insures that the code in the finally block will get 
executed before execution leaves the try block. Take, for example, the following code: 


int ClintSimFunc (int TodaysTask) { 


__try { 

switch (TodaysTask) { 

case THEGOOD: 
//Do the good stuff. 
return 1; 

case THEBAD: 
//Do the bad stuff. 
return 2; 

case THEUGLY: 
//Do the ugly stuff. 


break; 

} 

// Climb the Eiger. 

return Q; 
} 
__finally { 

// Reload the .44. 
} 


In this example, the try block can be left three ways: returning after executing 
the Good case or the Bad case or after executing the Ugly case, which breaks and 
executes the Eiger code. However the code exits the try block, Clint’s gun is always 
reloaded because the finally block is always executed. 

It works out that having the compiler build the code to protect the try block exits 
tends to create a fair amount of extra code. To help, you can use another statement, 
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__leave, which makes it easier for the compiler to recognize what’s happening and 
make a code-efficient path to the finally block. Using the __/eave statement, the code 
above becomes 


int ClintSimFunc (int TodaysTask) { 
int nFistfull; 


__try { 
switch (TodaysTask) { 
case THEGOOD: 


//Do the good stuff. 
nFistfull = 1; 
__leave; 

case THEBAD: 
//Do the bad stuff. 
nFistfull = 2; 
__leave; 

case THEUGLY: 
//Do the ugly stuff. 
break; 

} 

// Climb the Eiger. 

nFistFull = @; 


y; 
// The code falls into the __finally block. 
__finally { 
// Reload the .44. 
} 


return nFistfull; 


The __try, __ finally block is helpful for writing clean code because you can 
use the __/eave statement to jump out of a sequence of statements that build upon 
one another and put all the cleanup code in the finally block. The finally block also 
has a place in structured exception handling since the finally code is executed if an 
exception in the try block causes a premature exit of the block. 

In the past three chapters, I’ve covered the basics of the Windows CE kernel 
from memory to files to processes and threads. Now it’s time to break from this low- 
level stuff and starting looking outward. The next section covers the different com- 
munication aspects of Windows CE. I start at the low level, with explanations of basic 
serial and I/R communication and TAPI. Chapter 10 covers networking from a Win- 
dows CE perspective. Finally, Chapter 11 covers Windows CE to PC communications. 
That’s a fair amount of ground to cover. Let’s get started. 
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If there’s one area of the Win32 API that Windows CE doesn’t skimp, it’s in commu- 
nication. It makes sense. Systems running Windows CE are either mobile, requiring 
extensive communication functionality, or they’re devices generally employed to 
communicate with remote servers. In this chapter, I introduce the low-level serial and 
infrared communication APIs. You use the infrared port at this level in almost the same 
manner as a serial port. The only functional difference is that infrared transmission is 
half duplex, that is, transmission can occur in only one direction at a time. 


BASIC DRIVERS 


Before I can delve into the serial drivers, we must take a brief look at how Windows CE 
handles drivers in general. Windows CE separates device drivers into two main 
groups: native and stream interface. Native drivers, sometimes called built-in drivers, 
are those device drivers that are required for the hardware and were created by the 
OEM when the Windows CE hardware was designed. Among the devices that have 
native drivers are the keyboard, the touch panel, audio, and the PCMCIA controller. 
These drivers might not support the generic device driver interface I describe below. 
Instead, they might extend the interface or have a totally custom interface to the 
operating system. Native drivers frequently require minor changes when a new 
version of the operation system is released. These drivers are designed using 
the OEM adaptation kit supplied by Microsoft. A more general adaptation kit, the 
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Embedded Toolkit CETK), also enables you to develop built-in drivers. However these 
drivers are developed, they’re tightly bound to the Windows CE operating system and 
aren't usually replaced after the device has been sold. 

On the other hand, stream interface device drivers (which used to be referred 
to as installable drivers) can be supplied by third-party manufacturers to support 
hardware added to the system. Since Windows CE systems generally don’t have a bus 
such as an ISA bus or a PCI bus for extra cards, the additional hardware is usually 
installed via a PCMCIA or a Compact Flash slot. In this case, the device driver would 
use functions provided by the low-level PCMCIA driver to access the card in the 
PCMCIA or the Compact Flash slot. 

In addition, a device driver might be written to extend the functionality of an 
existing driver. For example, you might write a driver to provide a compressed or 
encrypted data stream over a serial link. In this case, an application would access the 
encryption driver, which would then in turn use the serial driver to access the serial 
hardware. | | 

Device drivers under Windows CE operate at the same protection level as ap- 
plications. They differ from applications in that they’re DLLs. Most drivers are loaded 
by the device manager process (DEVICE.EXE) when the system boots. All these driv- 
ers, therefore, share the same process address space. Some of the built-in drivers, 
on the other hand, are loaded by GWE (GWES.EXE). (GWE stands for Graphics 
Windowing and Event Manager.) These drivers include the display driver C(DDI.DLL) 
as well as the keyboard and touch panel (or mouse) drivers. 


Driver Names 


Stream interface device drivers are identified by a three-character name followed by 
a single digit. This scheme allows for 10 device drivers of one name to be installed 
on a Windows CE device at any one time. Here are a few examples of some three- 
character names currently in use: 


COM Serial driver 

ACM Audio compression manager 
WAV Audio wave driver 

CON Console driver 


When referencing a stream interface driver, an application uses the three- 
character name, followed by the single digit, followed by a colon (:). The colon is 
required under Windows CE for the system to recognize the driver name. 


Enumerating the Active Drivers 
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The documented method for determining what drivers are loaded onto a Windows CE 
system is to look in the registry under the key \Drivers\Active under HKEY_ 
LOCAL_MACHINE. The device manager dynamically updates the subkeys contained 
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here as drivers are loaded and unloaded from the system. Contained in this key is a 
list of subkeys, one for each active driver. The name of the key is simply a place- 
holder; it’s the values inside the keys that indicate the active drivers. Figure 9-1 shows 
the registry key for the COM1 serial driver on an HP 620. 


Drivers\BuiltIn\ Serial 


Figure 9-1. The registry’s active list values for the serial device driver for COM1. 


In Figure 9-1, the Name value contains the official five-character name Cfour char- 
acters plus a colon) of the device. The THnd and Hnd values are handles that are 
used internally by Windows CE. The interesting entry is the Key value. This value points 
to the registry key where the device driver stores its configuration information. This 
second key is necessary because the active list is dynamic, changing whenever a device 
is installed. In the case of the serial driver, its configuration data is generally stored 
in Drivers\BuiltIn\Serial although you shouldn’t hard code this value. Instead, you 
can look at the Key value in the active list to determine the location of a driver’s per- 
manent configuration data. The configuration data for the serial driver is shown in 
Figure 9-2. 


Unimodem.dll 
0 

COM 
Serial.Dll 


Oo 

0 

Serial Cable on COM1: 

10 00 00 00 05 00 0000 1001 00000... 


Sik ee ss : 


Figure 9-2. The registry entry for the serial driver. 


You can look in the serial driver registry key for such information as the name 
of the DLL that actually implements the driver, the three-letter prefix defining the driver 
name, the order in which the driver wants to be loaded, and something handy for 
user interfaces, the friendly name of the driver. Not all drivers have this friendly name, 
but when they do, it’s a much more user-friendly name than COM2 or NDSI1. 
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Drivers for PCMCIA or Compact Flash Cards have an additional value in their 
active list key. The Pnpid value contains the Plug and Play ID string for the card. While 
this string is more descriptive than the five-character driver name, some PCMCIA and 
Compact Flash Cards have their Pnpid strings registered in the system. If so, a regis- 
try key for the Pnpld is located in the Drivers\PCMCIA key under HKEY_LOCAL_ 
MACHINE. For example, a PCMCIA Card that had a Pnpld string This_is_a_pc_card 
would be registered under the key \Drivers\PCMCIA\This_is_a_pc_card. That key 
may contain a FriendlyName string for the driver. 

Following is a routine (and a small helper routine) that creates a list of active 
drivers and, if specified, their friendly names. The routine produces a series of Unicode 
strings, two for each active driver. The first string is the driver name, followed by its 
friendly name. If a driver doesn’t have a friendly name, a zero-length string is inserted 
in the list. The list ends with a zero-length string for the driver name. 


// AddToList - Helper routine 
int AddToList (LPTSTR *pPtr, INT *pnListSize, LPTSTR pszStr) { 
INT nLen = Istrlen (pszStr) + 1; 


if (*pnListSize < nLen) 
return -1; 

Tstrcpy (*pPtr, pszStr); 

*pPtr += nLen; 


*pnListSize -= nLen; 
return Q; 
} 
pf APP RASe SERRE ESR AS a ee kien sees Sea eit Ss See ie SSM ee cea eres re 
// EnumActiveDrivers - Produces a list of active drivers 
// 


int EnumActiveDrivers (LPTSTR pszDrvrList, int nListSize) { 
INT i = @, rc; 
HKEY hKey, hSubKey, hDrvrKey; 
TCHAR szKey[128], szValue[128]; 
LPTSTR pPtr = pszDrvrList; 
DWORD dwlype, dwSize; 


*pPtr = TEXT ('\@'); 
if (RegOpenKeyEx (HKEY_LOCAL_MACHINE, TEXT ("drivers\\active"), Q, 
Q@, &hKey) != ERROR_SUCCESS) 
return @; 


while (1) { 
// Enumerate active driver list. 
dwSize = sizeof (szKey); 
if (RegEnumKeyEx (hKey, i++, szKey, &dwSize, NULL, NULL, 
NULL, NULL) != ERROR_SUCCESS) 
break; 
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// Open active driver key. 
rc = RegOpenKkeyEx (hKey, szKey, @, @, &hSubKey); 
if (re != ERROR_SUCCESS) 

continue; 


// Get name of device. 
dwSize = sizeof (szValue); 
re = RegQueryValueEx (hSubKey, TEXT ("Name"), 8, &dwlype, 
(PBYTE)szValue, &dwSize); 
if (re != ERROR_SUCCESS) 
szValue[@] = TEXT ('\O@'); 


if (AddToList (&pPtr, &nListSize, szValue)) { 
re = -l:; 
RegCloseKey (hSubKey); 
break; 

} 


// Get friendly name of device. 
szValue[Q@] = TEXT ( ‘'\@'); 
dwSize = sizeof (szKey); 
re = RegQueryValueEx (hSubKey, TEXT ("Key"), 0, &dwType, 
(PBYTE)szKey, &dwSize); 
if (re == ERROR_SUCCESS) { 
// Get driver friendly name. 
if (RegOpenKeyEx (HKEY_LOCAL_MACHINE, szKey, 0, @, 
&hDrvrKey) == ERROR_SUCCESS) { 


dwSize = sizeof (szValue); 
RegQueryValueEx (hDrvrKkey, TEXT ("FriendlyName"), 0, 
&dwlype, (PBYTE)szValue, &dwSize); 
RegCloseKey (hDrvrKey); 
} 
} 
RegCloseKey (hSubKey) ; 
if (AddToList (&pPtr, &nListSize, szValue)) { 
re = -l; 
break; 
} 


RegCloseKey (hKey); 
// Add terminating zero. 
if (!rc) 


re = AddToList (&pPtr, &nListSize, TEXT ("")); 


return rc; 
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Reading and Writing Device Drivers 


Your application accesses device drivers under Windows CE through the file I/O func- 
tions, CreateFile, ReadFile, WriteFile, and CloseHandle. You open the device using 
CreateFile, with the name of the device being the five-character (three characters plus 
digit plus colon) name of the driver. Drivers can be opened with all the varied access 
rights: read only, write only, read/write, or neither read nor write access. 

Once a device is open, you can send data to it using WriteFile and can read 
from the device using ReadFile. As is the case with file operations, overlapped I/O 
isn’t supported for devices under Windows CE. The driver can be sent control char- 
acters using the function (not described in Chapter 7) DeviceloControl. The function 
is prototyped this way: 

BOOL DeviceIoControl (HANDLE hDevice, DWORD dwloControlCode, 

LPVOID IpInBuffer, DWORD ninBufferSize, 

LPVOID 1lpOutBuffer, DWORD nOutBufferSize, 

LPDWORD IpBytesReturned, 

LPOVERLAPPED 1p0Overlapped) ; 
The first parameter is the handle to the opened device. The second parameter, dwlo- 
ControlCode, is the IoCtl (pronounced eye-OC-tal) code. This value defines the op- 
eration of the call to the driver. The next series of parameters are generic input and 
output buffers and their sizes. The use of these buffers is dependent on the JoCi#/ code 
passed in dwloControlCode. The lpBytesReturned parameter must point toa DWORD 
value that will receive the number of bytes returned by the driver in the buffer pointed 
to by IpOutBuffer. 

Each driver has its own set of JoCtl codes. If you look in the source code for 
the example serial driver provided in the ETK, you'll see that the following JoCtl 
codes are defined for the COM driver. Note that these codes aren’t defined in the 
Windows CE SDK because an application doesn’t need to directly call DeviceloControl 
using these codes. 
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IOCTL_SERIAL_SET_BREAK_ON 
IOCTL_SERIAL_SET_DTR 
IOCTL_SERIAL_SET_RTS 
IOCTL_SERIAL_SET_XOFF 
IOCTL_SERIAL_GET_WAIT_MASK 
IOCTL_SERIAL_WAIT_ON_MASK 
IOCTL_SERIAL_GET_MODEMSTATUS 
IOCTL_SERIAL_SET_TIMEOUTS 
IOCTL_SERIAL_PURGE 
IOCTL_SERIAL_IMMEDIATE_CHAR 
IOCTL_SERIAL_SET_DCB 
IOCTL_SERIAL_DISABLE_IR 


IOCTL_SERIAL_SET_BREAK_OFF 
IOCTL_SERIAL_CLR_DTR 
IOCTL_SERIAL_CLR_RTS 
IOCTL_SERIAL_SET_XON 
IOCTL_SERIAL_SET_WAIT_MASK 
IOCTL_SERIAL_GET_COMMSTATUS 
IOCTL_SERIAL_GET_PROPERTIES 
IOCTL_SERIAL_GET_TIMEOUTS 
IOCTL_SERIAL_SET_QUEUE_SIZE 
IOCTL_SERIAL_GET_DCB 
IOCTL_SERIAL_ENABLE_IR 
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As you can see from the fairly self-descriptive names, the serial driver JoCtl func- 
tions expose significant function to the calling process. Windows uses these JoC#tl codes 
to control some of the specific features of a serial port, such as the handshaking lines 
and time outs. Each driver has its own set of JoCtl codes. I’ve shown the ones above 
simply as an example of how the DeviceloControl function is typically used. Under 
most circumstances, there’s no reason for an application to use the DeviceloControl 
function with the serial driver. Windows provides its own set of functions that then 
call down to the serial driver using DeviceloControl. 

Okay, we’ve talked enough about generic drivers. It’s time to sit down to the 
meat of the chapter—serial communication. I'll talk first about basic serial connec- 
tions, and then venture into infrared communication. Windows CE provides excel- 
lent support for serial communications, but the API is a subset of the API for 
Windows NT or Windows 98. Fortunately, the basics are quite similar, and the dif- 
ferences mainly inconsequential. 


BASIC SERIAL COMMUNICATION 


The interface for a serial device is a combination of generic driver I/O calls and spe- 
cific communication-related functions. The serial device is treated as a generic, in- 
stallable, stream device for opening, closing, reading, and writing the serial port. For 
configuring the port, the Win32 API supports a set of Comm functions. Windows CE 
supports most of the Comm functions supported by Windows NT and Windows 98. 

A word of warning: programming a serial port under Windows CE isn’t like 
programming one under MS-DOS. You can’t simply find the base address of the se- 
rial port and program the registers directly. While there are ways for a program to 
gain access to the physical memory space, every Windows CE device has a different 
physical memory map. Even if you solved the access problem by knowing exactly 
where the serial hardware resided in the memory map, there’s no guarantee the se- 
rial hardware is going to be compatible with the 8250 (or, these days, a 16550) serial 
interface we’ve all come to know and love in the PC world. In fact, the implementa- 
tion of the serial port on some Windows CE devices looks nothing like an 8250. 

But even if you know where to go in the memory map and the implementation 
of the serial hardware, you still don’t need to “hack down to the hardware.” The se- 
rial port drivers in Windows CE are efficient, interrupt-driven designs and are written 
to support its specific serial hardware. If you have any special needs not provided by 
the base serial driver, you can purchase the Embedded Toolkit and write a serial driver 
yourself. Aside from that extreme case, there’s just no reason not to use the published 
Win32 serial interface under Windows CE. 
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Opening and Closing a Serial Port 


As with all stream device drivers, a serial port device is opened using CreateFile. The 
name used needs to follow the standards I described previously, with the three let- 
ters COM followed by the number of the COM port to open and then a colon. The 
colon is required under Windows CE and is a departure from the naming convention 
used for device driver names used in Windows NT and Windows 98. The following 
line opens COM port 1 for reading and writing: 


hSer = CreateFile (TEXT ("COM1:"), GENERIC_READ | GENERIC_WRITE, 
Q@, NULL, OPEN_EXISTING, @, NULL); 


You must pass a 0 in the sharing parameter as well as in the security attributes 
and the template file parameters of CreateFile. Windows CE doesn’t support over- 
lapped I/O for devices, so you can’t pass the FILE_LFLAG_OVERLAPPED flag in the 
dwFlagsAndAttributes parameter. The handle returned is either the handle to the 
opened serial port or INVALID_HANDLE_VALUE. Remember that, unlike many of the 
Windows functions, CreateFile doesn’t return a 0 for a failed open. 

You close a serial port by calling CloseHandle, as in the following: 


CloseHandle (hSer); 


You don’t do anything differently when using CloseHandle to close a serial device 
than when you use it to close a file handle. 


Reading and Writing to a Serial Port 
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Just as you use the CreateFile function to open a serial port, you use the functions 
ReadFile and WriteFile to write to that serial port. Reading data from a serial port is 
as simple as making this call to ReadFile: 


INT rc; 
DWORD cBytes; 
BYTE ch; 


rc = ReadFile(hSer, &ch, 1, &cBytes, NULL); 


This call assumes the serial port has been successfully opened with a call to CreateFile. 
If the call is successful, one byte is read into the variable ch, and cBytes is set to the 
number of bytes read. 

Writing to a serial port is just as simple. The call would look something like the 
following: 


INT re; 
DWORD cBytes; 
BYTE ch; 


ch 
rc 


TEXT ('a'); 
WriteFile(hSer, &ch, 1, &cBytes, NULL); 
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This code writes the character a to the serial port previously opened. As you may 
remember from Chapter 7, both ReadFile and WriteFile return TRUE if successful. 

Since overlapped I/O isn’t supported under Windows CE, you should be care- 
ful not to attempt to read or write a large amount of serial data from your primary 
thread or from any thread that has created a window. Because those threads are also 
responsible for handling the message queues for their windows, they can’t be blocked 
waiting on a relatively slow serial read or write. Instead, you should use separate 
threads for reading and writing the serial port. 

You can also transmit a single character using this function: 


BOOL TransmitCommChar (HANDLE hFile, char cChar); 


The difference between TransmitCommcChar and WriteFile is that TransmitCommChar 
puts the character to be transmitted at the front of the transmit queue. When you call 
WriteFile, the characters are queued up after any characters that haven’t yet been trans- 
mitted by the serial driver. TransmitCommcChar allows you to insert control charac- 
ters quickly in the stream without having to wait for the queue to empty. 


Asynchronous Serial 1/O 


While Windows CE doesn’t support overlapped I/O, there’s no reason why you can’t 
use multiple threads to implement the same type of overlapped operation. All that’s 
required is that you launch separate threads to handle the synchronous I/O opera- 
tions while your primary thread goes about its business. In addition to using sepa- 
rate threads for reading and writing, Windows CE supports the Win32 WaitCommEvent 
function that blocks a thread until one of a group of preselected serial events occurs. 
I’ll demonstrate how to use separate threads for reading and writing a serial port in 
the CeChat example program later in this chapter. 

You can make a thread wait on serial driver events by means of the following 
three functions: 


BOOL SetCommMask (HANDLE hFile, DWORD dwEvtMask); 
BOOL GetCommMask (HANDLE hFile, LPDWORD lpEvtMask); 


and 


BOOL WaitCommEvent (HANDLE hFile, LPDWORD IpEvtMask, 
LPOVERLAPPED 1pOverlapped) ; 


To wait on an event, you first set the event mask using SetCommMask. The 
parameters for this function are the handle to the serial device and a combination of 
the following event flags: 


M EV_BREAK A break was detected. 
M EV_CTS The Clear to Send (CTS) signal changed state. 
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EV_DSR_ The Data Set Ready (DSR) signal changed state. 

EV_ERR An error was detected by the serial driver. 

EV_RISD The Receive Line Signal Detect (RLSD) line changed state. 
EV_RXCHAR A character was received. 

EV_RXFLAG An event character was received. 

EV_TXEMPTY The transmit buffer is empty. 


You can set any or all of the flags in this list at the same time using SetCommMask. 
You can query the current event mask using GetCommMask. 

To wait on the events specified by SetCommMask, you call WaitCommEvent. 
The parameters for this call are the handle to the device, a pointer to a DWORD that 
will receive the reason the call returned, and /pOverlapped, which under Windows CE 
must be set to NULL. The code fragment that follows waits on a character being re- 
ceived or an error. The code assumes that the serial port has already been opened 
and the handle is contained in bComPort. 


DWORD dwMask; 

// Set mask and wait. 

SetCommMask (hComPort, EV_RXCHAR | EV_ERR); 
if (WaitCommEvent (hComPort, &dwMask, 0) { 


// Use the flags returned in dwMask to determine the reason 
// for returning. 
Switch (dwMask) { 
case EV_RXCHAR: 
//Read character. 
break; 
case EV_ERR: 
// Process error. 
break; 


Configuring the Serial Port 
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Reading and writing to a serial port is fairly straightforward, but you also must con- 
figure the port for the proper baud rate, character size, and so forth. The masochist 
could configure the serial driver through device I/O control GOCTL) calls but the JoCtl 
codes necessary for this are exposed only in the Embedded Toolkit, not the Software 
Development Kit. Besides, here’s a simpler method. 

You can go a long way in configuring the serial port using two functions, 
GetCommState and SetCommState, prototyped here: 
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BOOL SetCommState (HANDLE hFile, LPDCB 1pDCB); 
BOOL GetCommState (HANDLE hFile, LPDCB 1pDCB); 


Both these functions take two parameters, the handle to the opened serial port and a 
pointer to a DCB structure. The extensive DCB structure is defined as follows: 


typedef struct _DCB { 
DWORD DCBlength; 
DWORD BaudRate; 
DWORD fBinary: 1; 
DWORD fParity: 1; 
DWORD fOutxCtsFlow:1; 
DWORD fOutxDsrFlow:1; 
DWORD fDtrControl:2; 
DWORD fDsrSensitivity:1; 
DWORD fTXContinueOnXoff:1; 
DWORD fOutxX: 1; 
DWORD fInX: 1; 
DWORD fErrorChar: 1; 
DWORD fNull: 1; 
DWORD fRtsControl:2; 
DWORD fAbortOnError:1; 
DWORD fDummy2:17; 
WORD wReserved; 
WORD XonLim; 
WORD XoffLim; 
BYTE ByteSize; 
BYTE Parity; 
BYTE StopBits; 
char XonChar; 
char XoffChar; 
char ErrorChar; 
char EofChar; 
char EvtChar; 
WORD wReservedl1; 

} DCB; 


As you can see from the structure, the SetCommState can set a fair number of states. 
Instead of attempting to fill out the entire structure from scratch, you should use the 
best method of modifying a serial port, which is to call GetCommState to fill in a DCB 
structure, modify the fields necessary, and then call SetCommState to configure the 
serial port. 

The first field in the DCB structure, DCBlength, should be set to the size of the 
structure. The BaudkRate field should be set to one of the baud rate constants defined 
in WINBASE.H. The baud rate constants range from CBR_110 for 110 bits per second 
to CBR_256000 for 256 kilobits per second (Kbps). Just because constants are defined 
for speeds up to 256 Kbps doesn’t mean that all serial ports support that speed. To 
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determine what baud rates a serial port supports, you can call GetCommProperties, 
which I'll describe shortly. Windows CE devices generally support speeds up to 115 
Kbps, although some support faster speeds. The fBinary field must be set to TRUE 
because no Win32 operating system currently supports a nonbinary serial transmit 
mode familiar to MS-DOS programmers. The fParity field can be set to TRUE to en- 
able parity checking. 

The fOutxCtsFlow field should be set to TRUE if the output of the serial port 
should be controlled by the port CTS line. The fOutxDsrFlow field should be set to 
TRUE if the output of the serial port should be controlled by the DSR line of the 
serial port. The fDtrControl field can be set to one of three values: DTR_ 
CONTROL_DISABLE, which disables the DTR (Data Terminal Ready) line and leaves 
it disabled; DTR_CONTROL_ENABLE, which enables the DTR line; or DTR_ 
CONTROL_HANDSHAKE, which tells the serial driver to toggle the DTR line in re- 
sponse to how much data is in the receive buffer. 

The fDsrSensitivity field is set to TRUE, and the serial port ignores any incom- 
ing bytes unless the port DSR line is enabled. Setting the f7XContinueOnXoff field 
to TRUE tells the driver to stop transmitting characters if its receive buffer has reached 
its limit and the driver has transmitted an XOFF character. Setting the fOutX field to 
TRUE specifies that the XON/XOFF control is used to control the serial output. Set- 
ting the /InX field to TRUE specifies that the XON/XOFF control is used for the input 
serial stream. 

The fErrorChar and ErrorChar fields are ignored by the default implementa- 
tion of the Windows CE serial driver although some drivers might support these fields. 
Likewise, the fAbortOnError fields is also ignored. Setting the fNull field to TRUE tells 
the serial driver to discard null bytes received. 

The fRisControl field specifies the operation of the RTS (Request to Send) line. 
The field can be set to one of the following: RTS_CONTROL_DISABLE, indicating that 
the RTS line is set to the disabled state while the port is open; RTS_CONTROL_ENABLE, 
indicating that the RTS line is set to the enabled state while the port is open; or 
RTS_CONTROL_HANDSHAKE, indicating that the RTS line is controlled by the driver. 
In this mode, if the serial input buffer is less than half full, the RTS line is enabled 
and disabled otherwise. Finally, RTS_CONTROL_TOGGLE indicates the driver enables 
the RTS line if there are bytes in the output buffer ready to be transmitted and dis- 
ables the line otherwise. 

The XonLim field specifies the minimum number of bytes in the input buffer 
before an XON character is automatically sent. The XoffLim field specifies the maxi- 
mum number of bytes in the input buffer before the XOFF character is sent. This limit 
value is computed by taking the size of the input buffer and subtracting the value in 
XoffLim. In the sample Windows CE implementation of the serial driver provided in 
the ETK, the XonLim field is ignored and XON and XOFF characters are sent based 
on the value in XoffLim. However, this behavior might differ in some systems. 
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The next three fields, ByteSize, Parity, and StopBits, define the format of the 
serial data word transmitted. The ByteSize field specifies the number of bits per byte, 
usually a value of 7 or 8, but in some older modes the number of bits per byte can be 
as small as 5. The parity field can be set to the self-explanatory constants EVENPARITY, 
MARKPARITY, NOPARITY, ODDPARITY, or SPACEPARITY. The StopBits field should 
be set to ONESTOPBIT, ONESSTOPBITS, or TWOSTOPBITS depending on whether 
you want one, one and a half, or two stop bits per byte. 

The next two fields, XonChar and XoffChar, let you specify the XON and XOFF 
characters. Likewise, the EvtChar field lets you specify the character used to signal 
an event. If an event character is received, an EV_RXFLAG event is signaled by the 
driver. This “event” is what triggers the WaitCommEvent function to return if the 
EV_RXFLAG bit is set in the event mask. 


Setting the Port Timeout Values 


As you can see, SetCommState can fine-tune, to almost the smallest detail, the opera- 
tion of the serial driver. However, one more step is necessary—setting the timeout 

_ values for the port. The time out is the length of time Windows CE waits on a read or 
write operation before ReadFile or WriteFile automatically returns. The functions that 
control the serial time outs are the following: 


BOOL GetCommTimeouts (HANDLE hFile, LPCOMMTIMEOUTS 1pCommTimeouts) ; 
and 
BOOL SetCommTimeouts (HANDLE hFile, LPCOMMTIMEOUTS 1pCommTimeouts) ; 


Both functions take the handle to the open serial device and a pointer to a COMM- 
TIMEOUTS structure, defined as the following: 


typedef struct _COMMTIMEOUTS { 
DWORD ReadIntervalTimeout; 
DWORD ReadTotalTimeoutMultiplier; 
DWORD ReadTotalTimeoutConstant; 
DWORD WriteTotalTimeoutMultiplier; 
DWORD WriteTotalTimeoutConstant; 

} COMMTIMEOUTS; 


The COMMTIMEOUTS structure provides for a set of timeout parameters that time 
both the interval between characters and the total time to read and write a block of 
characters. Time outs are computed in two ways. First ReadIntervalTimeout speci- 
fies the maximum interval between characters received. If this time is exceeded, the 
ReadFile call returns immediately. The other time out is based on the number of char- 
acters you're waiting to receive. The value in ReadTotalTimeoutMultiplier is multi- 
plied by the number of characters requested in the call to ReadFile, and is added to 
ReadTotalTimeoutConstant to compute a total time out for a call to ReadFile. 
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The write time out can be specified only for the total time spent during the 
WriteFile call. This time out is computed the same way as the total read time out, by 
specifying a multiplier value, the time in WriteTotalTimeoutMultiplier, and a constant 
value in WriteTotalTimeoutConstant. All of the times in this structure are specified in 
milliseconds. 

In addition to the basic time outs that I just described, you can set values in 
the COMMTIMEOUTS structure to control whether and exactly how time outs are 
used in calls to ReadFile and WriteFile. You can configure the time outs in the fol- 
lowing ways: 


M Time outs for reading and writing as well as an interval time out. Set the 
fields in the COMMTIMEOUTS structure for the appropriate timeout 
values. 


— Time outs for reading and writing with no interval time out. Set Read- 
IntervalTimeout to 0. Set the other fields for the appropriate timeout 
values. 


M ReadFile returns immediately regardless of whether there is data to be read. 
Set ReadIntervalTimeout to MAXDWORD. Set ReadTotalTimeoutMultiplier 
and ReadTotalTimeoutConstant to 0. 


M £ keadFile doesn’t have a time out. The function doesn’t return until the 
proper number of bytes is returned or an error occurs. Set ReadInterval- 
Timeout, ReadTotalTimeoutMultiplier, and ReadTotalTimeoutConstant 
to 0. 


M WriteFile doesn’t have a time out. Set WriteTotalTimeoutMultiplier and 
WriteTotalTimeoutConstant to 0. | 


The timeout values are important because the worst thing you can do is to spin 
in a loop waiting on characters from the serial port. While the calls to ReadFile and 
WriteFile are waiting on the serial port, the calling threads are efficiently blocked on 
an event object internal to the driver. This saves precious CPU and battery power during 
the serial transmit and receive operations. Of course, to block on the ReadFile and 
WriteFile, you'll have to create secondary threads because you can’t have your pri- 
mary thread blocked waiting on the serial port. 

Another call isn’t quite as useful—SetupComm, prototyped this way: 


BOOL SetupComm (HANDLE hFile, DWORD dwInQueue, DWORD dwOutQueue) ; 


This function lets you specify the size of the input and output buffers for the driver. 
However, the sizes passed in SetupComm are only recommendations, not require- 
ments to the serial driver. For example, the example implementation of the serial driver 
in the ETK ignores these recommended buffer sizes. 
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Querying the Capabilities of the Serial Driver 


The configuration functions enable you to configure the serial driver, but with varied 
implementations of serial ports you need to know just what features a serial port 
supports before you configure it. The function GetCommProperties provides just this 
service. The function is prototyped this way: 


BOOL GetCommProperties (HANDLE hFile, LPCOMMPROP IpCommProp) ; 


GetCommProperties takes two parameters: the handle to the opened serial driver, and 
a pointer to a COMMPROP structure defined as 


typedef struct _COMMPROP { 
WORD wPacketLength; 
WORD wPacketVersion; 
DWORD dwServiceMask; 
DWORD dwReservedl1; 
DWORD dwMaxTxQueue; 
DWORD dwMaxRxQueue; 
DWORD dwMaxBaud; 
DWORD dwProvSubType; 
DWORD dwProvCapabilities; 
DWORD dwSettableParams; 
DWORD dwSettableBaud; 
WORD wSettableData; 
WORD wSettableStopParity; 
DWORD dwCurrentTxQueue; 
DWORD dwCurrentRxQueue; 
DWORD dwProvSpecl; 
DWORD dwProvSpec2; 
WCHAR wcProvChar[1]; 

} COMMPROP; 


As you can see from the fields of the COMMPROP structure, GetCommProperties 
returns generally enough information to determine the capabilities of the device. Of 
immediate interest to speed demons is the dwMaxBaud field that indicates the maxi- 
mum baud rate of the serial port. The dwSettableBaud field contains bit flags that 
indicate the allowable baud rates for the port. Both these fields use bit flags that 
are defined in WINBASE.H. These constants are expressed as BAUD_xxxx, as in 
BAUD_19200, which indicates the port is capable of a speed of 19.2 kbps. Note that 
these constants are not the constants used to set the speed of the serial port in the 
DGB structure. Those constants are numbers, not bit flags. To set the speed of a COM 
port in the DCB structure to 19.2 kbps, you would use the constant CBR_19200 in the 
BaudRate field of the DCB structure. 

Starting back at the top of the structure are the wPacketLength and wPacketVersion 
fields. These fields allow you to request more information from the driver than is 
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supported by the generic call. The dwServiceMask field indicates what services the 
port supports. The only service currently supported is SP_SERIALCOMM, indicating 
that the port is a serial communication port. 

The dwMaxTxQueue and dwMaxRxQueue fields indicate the maximum size 
of the output and input buffers internal to the driver. A value of 0 in these fields 
indicates that you’ll encounter no limit in the size of the internal queues. The 
dwCurrentTxQueue and dwCurrentRxQueue fields indicate the current size for the 
queues. These fields are 0 if the queue size can’t be determined. 

The dwProvSubType field contains flags that indicate the type of serial port 
supported by the driver. Values here include PST_RS232, PST_RS422, and PST_RS423, 
indicating the physical layer protocol of the port. PST_.MODEM indicates a modem 
device, and PST_FAX tells you the port is a fax device. This field reports what the 
driver thinks the port is, not what device is attached to the port. For example, if an 
external modem is attached to a standard, RS-232 serial port, the driver returns the 
PST_RS232 flag, not the PST_MODEM flag. 

The dwProvCapabiilities field contains flags indicating the handshaking the port 
supports, such as XON/XOFF, RTS/CTS, and DTR/DSR. This field also shows you 
whether the port supports setting the characters used for XON/XOFF, parity check- 
ing, and so forth. The dwSettableParams, dwSettableData, and dwSettableStopParity 
fields give you information about how the serial data stream can be configured. 
Finally, the fields dwProvSpec1, dwProvSpec2, and wcProvChar are used by the driver 
to return driver-specific data. 


Controlling the Serial Port 
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You can stop and start a serial stream using the following functions: 
BOOL SetCommBreak (HANDLE hFile); 

and 

BOOL ClearCommBreak (HANDLE hFile); 


The only parameter for both these functions is the handle to the opened COM port. 
When SetCommBreak is called, the COM port stops transmitting characters and places 
the port in a break state. Communication is resumed with the ClearCommBreak 
function. 

You can clear out any characters in either the transmit or receive queues inter- 
nal to the serial driver using this function: 


BOOL PurgeComm (HANDLE hFile, DWORD dwFlags); 


The dwFlags parameter can be a combination of the flags PURGE_TXCLEAR and 
PURGE_RXCLEAR. These flags terminate any pending writes and reads and reset the 
queues. In the case of PURGE_RXCLEAR, the driver also clears any receive holds due 
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to any flow control states, transmitting an XON character if necessary, and setting RTS 
and DTR if those flow control methods are enabled. Since Windows CE doesn’t sup- 
port overlapped I/O, the flags PURGE_TXABORT and PURGE_RXABORT, used un- 
der Windows NT and Windows 98, are ignored. 

The EscapeCommFunction provides a more general method of controlling the 
serial driver. It allows you to set and clear the state of specific signals on the port. On 
Windows CE devices, it’s also used to control serial hardware that’s shared between 
the serial port and the IrDA port. C’ll talk more about infrared data transmission and 
the Infrared Data Association UrDA) standard later in this chapter.) The function is 
prototyped as 


BOOL EscapeCommFunction (HANDLE hFile, DWORD dwFunc); 

The function takes two parameters, the handle to the device and a set of flags in 
dwFunc. The flags can be one of the following values: 

M SETDTR Sets the DTR signal. 

M cCLIRDTR Clears the DTR signal. 

M SETRTS Sets the RTS signal 

M cCIRRTS Clears the RTS) ignal. 

M SETXOFF ‘Tells the driver to act as if an XOFF character has been 


received. 
M SETXON Tells the driver to act as ifan XON character has been received. 
M ###SETBREAK Suspends serial transmission and sets the port in a break state. 
M ###CIRBREAK Resumes serial transmission from a break state. 
M SETIR ‘Tells the serial port to transmit and receive through the infrared 
transceiver. 
M@ CTRIR ‘Tells the serial port to transmit and receive through the standard 


serial transceiver. 


The SETBREAK and CLRBREAK commands act identically to SetCommBreak 
and ClearCommBreak and can be used interchangeably. For example, you can use 
EscapeCommFunction to put the port in a break state and ClearCommBreak to 
restore communication. 


Clearing Errors and Querying Status 
The function 


BOOL ClearCommError (HANDLE hFile, LPDWORD JpErrors, LPCOMSTAT IpStat); 
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performs two functions. As you might expect from the name, it clears any error states 
within the driver so that I/O can continue. The serial device driver is responsible for 
reporting the errors. The default serial driver returns the following flags in the vari- 
able pointed to by /pErrors: CE_LOVERRUN, CE_RXPARITY, CE_FRAME, and CE_ 
TXFULL. ClearCommError also returns the status of the port. The third parameter of 
ClearCommError is a pointer to a COMSTAT structure defined as 


typedef struct _COMSTAT { 
DWORD fCtsHold : 1; 
DWORD fDsrHold : 1; 
DWORD fRisdHold : 1; 
DWORD fXoffHold : 1; 
DWORD fXoffSent : 1 
DWORD fEof : 1; 
DWORD fTxim : 1; 
DWORD fReserved : 25; 
DWORD cbInQue; 
DWORD cbOutQue; 

} COMSTAT; 


The first five fields indicate that serial transmission is waiting for one of the 
following reasons. It’s waiting for a CTS signal, waiting for a DSR signal, waiting for 
a Receive Line Signal Detect (also known as a Carrier Detect), waiting for an XON 
character, or it’s waiting because an XOFF character was sent by the driver. The fEor 
field indicates that an end-of-file character has been received. The f7xim field is TRUE 
if a character placed in the queue by the TransmitCommcChar function instead of a call 
to WriteFile is queued for transmission. The final two fields, cbInQue and cbOutQue, 
return the number of characters in the input and output queues of the serial driver. 

The function | 


BOOL GetCommModemStatus (HANDLE hFile, LPDWORD 1lpModemStat) ; 

returns the status of the modem control signals in the variable pointed to by 
lpModemsStat. The flags returned can be any of the following: 

M MS_CTS_ON Clear to Send (CTS) is active. 

M MS_DSR_ON Data Set Ready (DSR) is active. 

M MS_RING_ON Ring Indicate (RD is active. 

M MS_RISD_ON Receive Line Signal Detect (RLSD) is active. 


Stay’n Alive 


One of the issues with serial communication is preventing the system from powering 
down while a serial link is active. A Windows CE system determines activity by the 
number of key presses and screen taps. It doesn’t take into account such tasks as a 
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serial port transmitting data. To prevent a Windows CE device from powering off, 
you can simulate a keystroke using either of the following functions: 


VOID keybd_event (BYTE bVk, BYTE bScan, DWORD dwFlags, 
DWORD dwExtralInfo); 


or 
UINT SendInput (UINT nInputs, LPINPUT pInputs, int cbSize); 


These functions can be used to simulate a keystroke that resets the activity timer used 
by Windows CE to determine when the system should automatically power down. 
Windows CE supports an additional constant for both these functions—-KEYEVENTF_ 
SILENT, which prevents the default keyboard click sound from being played. 


THE INFRARED PORT 


Windows CE devices almost always have an infrared, IrDA-compatible serial port. In 
fact, all H/PC and Palm-size PC systems are guaranteed to have one. The IR ports on 
Windows CE devices are IrDA (Infrared Data Association) compliant. The IrDA stan- 
dard specifies everything from the physical implementation, such as the frequency 
of light used, to the handshaking between devices and how remote systems find each 
other and converse. 

The IR port can be used in a variety of ways. At the most basic level, the port 
can be accessed as a serial port with an IR transmitter and receiver attached. This 
method is known as raw IR. When you’re using raw IR, the port isn’t IrDA compliant 
because the IrDA standard requires the proper handshaking for the link. However, 
raw IR gives you the most control over the IR link. A word of warning: While all Win- 
dows CE devices I know currently support raw IR, some might not in the future. 

You can also use the IR port in IrComm mode. In this mode, the IR link looks 
like a serial port. However, under the covers, Windows CE works to hide the differ- 
ences between a standard serial port and the IR link. This is perhaps the easiest way 
to link two custom applications because the applications can use the rather simple 
Comm API while Windows CE uses the IrDA stack to handle the IR link. 

The most robust and complex method of using the IR port is to use IrSock. In 
this mode, the IR link appears to be just another socket. IrSock is an extension to 
WinSock, the Windows version of the socket interface used by applications commu- 
nicating with TCP/IP. I’ll cover WinSock in Chapter 10, so I’ll defer any talk of IrSock 
until then. 


Raw IR 


As I mentioned previously, when you use raw IR you're mainly on your own. You 
essentially have a serial port with an IR transceiver attached to it. Since both the trans- 
mitter and receiver use the same ether (the air), collisions occur if you transmit at the 
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same time that you’re receiving a stream of data from another device. This doesn’t 
happen when a serial cable connects two serial ports because the cable gives you 
separate transmit and receive wires that can be used at the same time. 


Finding the raw IR port 

To use raw IR, you must first find the serial port attached to the IR transceiver. On 
some Windows CE units, the serial port and the IR port use the same serial hardware. 
This means you can’t use the serial port at the same time you use the IR port. Other 
Windows CE devices have separate serial hardware for the IR port. Regardless of how 
a device is configured, Windows CE gives you a separate instance of a COM driver 
for the IR port that’s used for raw IR mode. 

There is no official method of determining the COM port used for raw IR. How- 
ever, the following technique works for current devices. To find the COM port 
used for raw IR, look in the registry in the \Comm\IrDA key under HKEY_LOCAL_ 
MACHINE. There, you should find the Port key that contains the COM port number 
for the raw IR device. Below is a short routine that returns the device name of the 
raw IR port. 


// GetRawIrDeviceName - Returns the device name for the RawIR com port 
// 
INT GetRawIrDeviceName (LPTSTR pDevName) { 

DWORD dwSize, dwlype, dwData; 

HKEY hKey; 

INT re; 


*pDevName = TEXT ('\@'); 

// Open the IrDA key. 

if (RegOpenKeyEx (HKEY_LOCAL_MACHINE, TEXT ("Comm\\IrDA"), @, 
Q@, &hKey) == ERROR_SUCCESS) { 


‘// Query the device number. 

dwSize = sizeof (dwData); 

if (RegQueryValueEx (hKey, TEXT ("Port"), 0, &dwType, 
(PBYTE)&dwData, &dwSize) == ERROR_SUCCESS) 


// Check for valid port number. Assume buffer > 5 chars. 
if (dwData < 10) 
wsprintf (pDevName, TEXT ("COM%d:"), dwData); 


RegCloseKey (hKey); 
} 


return Istrien (pDevName) ; 
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Using raw IR 

Once you have the port name, you must perform one more task before you can use 
the port. If the COM port hardware is being shared by the serial port and the IR port, 
you must tell the driver to direct the serial stream through the IR transceiver. You do 
this by first opening the device and calling EscapeCommFunction. The command 
passed to the device is SETIR. When you’ve finished using the IR port, you should 
call EscapeCommFunction again with the command CLRIR to return the port back to 
its original serial function. 

Once the port is set up, there’s one main difference between raw IR and stan- 
dard serial communication. You have to be careful when using raw IR not to transmit 
while another device is also transmitting. The two transmissions will collide, corrupt- 
ing both data streams. With raw IR, you’re also responsible for detecting the other 
device and handling the dropped bytes that will occur as the infrared beam between 
the two devices is occasionally broken. 


irComm 


Using IrComm is much easier than using raw IR. IrCcomm takes care of remote device 
detection, collision detection, and data buffering while communication with the other 
device is temporally interrupted. The disadvantage of IrComm is that it’s a point-to- 
point protocol—only two devices can be connected. In most instances, however, this 
is sufficient. 


Finding the IrComm port 

Here again, there’s no official method for determining the Ircomm port. But you should 
be able to find the Ircomm port by looking in the registry under the Drivers\builtin 
\IrCOMM key under HKEY_LOCAL_MACHINE. The item to query is the Index value, 
which is the COM device number for the IrCcomm port. Following is a routine that 
returns the device name of the IrComm port. 


// GetIrCommDeviceName - Returns the device name for the IrComm port 
// 
INT GetIrCommDeviceName (LPTSTR pDevName) { 

DWORD dwSize, dwlype, dwData; 

HKEY hKey; 


*pDevName = TEXT ('\@'); 

// Open the IrDA key. 

if (RegOpenKeyEx (HKEY_LOCAL_MACHINE, 
TEXT ("Drivers\\BuiltIn\\IrCOMM"), @, 
Q@, &hKey) == ERROR_SUCCESS) { 


(continued) 
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// Query the device number. 

dwSize = sizeof (dwData); 

if (RegQueryValueEx (hKey, TEXT ("Index"), 0, &dwType, 
(PBYTE)&dwData, &dwSize) == ERROR_SUCCESS) 


// Check for valid port number. Assume buffer > 5 chars. 
if (dwData < 10) 
wsprintf (pDevName, TEXT ("COM%d:"), dwData); 


RegCloseKey (hKey); 


} 


return lstrlen (pDevName); 


The IrComm port is different in a number of ways from the serial port and the 
raw IR port. These differences arise from the fact that the IrComm port is a simulated 
port, not a real device. The IrComm driver uses IrSock to manage the IR link. The 
driver is then responsible only for reflecting the data stream and a few control char- 
acters to simulate the serial connection. If you try to query the communication set- 
tings for the IrComm port using GetCommsState, the DCB returned is all zeros. If you 
try to set a baud rate or some of the other parameters, and later call GetCommState 
again, the DCB will still be 0. IrSock manages the speed and the handshaking proto- 
col, so IrCcomm simply ignores your configuration requests. 

On the other hand, the Ircomm driver happily queues up pending writes wait- 
ing on another Ircomm device to come within range. After the IrCcomm driver auto- 
matically establishes a link, it transmits the pending bytes to the other device. This 
assistance is a far cry from raw IR and is what makes using IrComm so easy. 

The best way to learn about the characteristics of the two methods of IR com- 
munication I’ve described is to use them. Which brings us to this chapter’s example 
program. 


THE CECHAT EXAMPLE PROGRAM 
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The CeChat program is a simple point-to-point chat program that connects two Win- 
dows CE devices using one of the three methods of serial communication covered in 
this chapter. The CeChat window is shown in Figure 9-3. Most of the window is taken 
up by the receive text window. Text received from the other device is displayed here. 
Along the bottom of the screen is the send text window. If you type characters here 
and either hit the Enter key or tap on the Send button, the text is sent to the other 
device. The combo box on the command bar selects the serial medium to use: stan- 
dard serial, raw IR, or IrComm. 
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Figure 9-3. The CeChat window. 


The source code for CeChat is shown in Figure 9-4. CeChat uses three threads 
to accomplish its work. The primary thread manages the window and the message 
loop. The two secondary threads handle reading from and writing to the appropri- 
ate serial port. 


Figure 9-4. The CeChat source code. (continued) 
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The send thread is actually quite simple. All it does is block on an event that 
was created when CeChat was started. When the event is signaled, it reads the text 
from the send text edit control and calls WriteFile. Once that has completed, the send 
thread clears the text from the edit control and loops back to where it blocks again. 

In the CeChat window shown in Figure 9-3 on page 561, the program reports 
that it can’t open COM1; this is because COM1 was being used by PC Link to connect 
to my PC. One of the problems with debugging serial programs on the H/PC or 
Palm-size PC is that you’re generally using the one port that attaches to the PC. In 
these situations, it helps to have a secondary communication path from the PC to 
the Windows CE device. While you could put an additional serial PCMCIA Card into 
the H/PC to add ports, a faster link can be made with a PCMCIA Ethernet Card. Which 
brings us right to the next chapter, “Windows Networking and IrSock.” 
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Windows 
Networkin 
and IrSoc 


Networks are at the heart of modern computer systems. Over the years, Microsoft 
Windows has supported a variety of networks and networking APIs. The evolving 
nature of networking APIs along with the need to keep systems backward compat- 
ible has resulted in a huge array of overlapping functions and parallel APIs. As in 
many places in Windows CE, the networking API is a subset of the vast array of net- 
working functions supported under Windows NT and Windows 98. 

Windows CE supports a variety of networking APIs. This chapter covers two. 
First is the Windows Networking API, WNet. This API supports basic network con- 
nections so that a Windows CE device can access disks and printers on a network. 

Windows CE also supports a subset of the WinSock 1.1 API. ’'m not going to 
cover the complete WinSock API because plenty of other books do that. I'll spend 
some time covering what is directly relevant to Windows CE developers. Of particu- 
lar interest is the fact that that WinSock is the high-level API to the IrDA infrared 
communication stack. I’ll also cover another extension to WinSock, the Internet con- 
trol message protocol (CMP) functions that allow Windows CE applications to ping 
other machines on a TCP/IP network. 


579 


Part Ill 


WINDOWS NETWORKING SUPPORT 


The WNet API is a provider-independent interface that allows Windows applications 
to access network resources without regard for the network implementation. The 
Windows CE version of the WNet API has fewer functions but provides the basics so 
that a Windows CE application can gain access to shared network resources, such as 
disks and printers. The WNet API is implemented by a “redirector” DLL that trans- 
lates the WNet functions into network commands for a specific network protocol. 

By default, the only network supported by the WNet API is Windows Network- 
ing. Support for even this network is limited by the fact that redirector files that imple- 
ment Windows Networking aren’t bundled with most H/PCs or Palm-size PCs. The 
two files that implement this support, REDIR.DLL and NETBIOS.DLL, are available 
from Microsoft. As a convenience, I’ve also included them on the book’s companion 
disc as well. As an aside, the NetBIOS DLL doesn’t export a NetBIOS-like interface to 
applications or drivers. 


WNet Functions 
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Windows CE’s support for the WNet functions started with Windows CE 2.0. As with 
other areas in Windows CE, the WNet implementation under Windows CE is a subset 
of the same API on the desktop, but support is provided for the critical functions while 
eliminating the overlapping and obsolete functions. For example, the standard WNet 
API contains four different and overlapping WNetAddConnection functions while 
Windows CE supports only one, WNetAddConnection3. | 

For the WNet API to work, the redirector DLLs must be installed in the \windows 
directory. In addition, the network control panel, also a supplementary component 
On most systems, must be used to configure the network card so that it can access 
the network. If the redirector DLLs aren’t installed, or an error occurs configuring or 
initializing the network adapter, the WNet functions return the error code ERROR_ 
NO_NETWORK. 


Conventions of UNC 
Network drives can be accessed in one of two ways. The first method is to explicitly 
name the resource using the Universal Naming Convention (UNC) naming syntax, 
which is a combination of the name of the server and the shared resource. An ex- 
ample of this is \\BJIGSRVR\DRVC, where the server name is BIGSERV and the re- 
source on the server is named DRVC. The leading double backslashes immediately 
indicate that the name is a UNC name. Directories and filenames can be included 
in the UNC name, as in \\bigserur\drvuc\dir2\file1 .ext. Notice that I changed case in 
the two names. That doesn’t matter because UNC paths are case insensitive. 

As long as the WNet redirector is installed, you can use UNC names wherever 
you use standard filenames in the Windows CE API. You'll have problems, though, 
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with some programs, including, in places, the Windows CE shell, where the applica- 
tion doesn’t understand UNC syntax. For example, the Explorer in a Windows CE 2.0 
H/PC device understands UNC names, but the File Open dialog box on the same 
system doesn't. 


Mapping a remote drive 

To get around applications that don’t understand UNC names, you can map a net- 
work drive to a local name. When a network drive is mapped on a Windows CE sys- 
tem, the remote drive appears as a folder in the \network folder in the object store. 
The \network folder isn’t a standard folder; in fact, before Windows CE 2.1, it didn’t 
even show up in the Explorer. (For systems based on Windows CE 2.1, the visi- 
bility of the \network folder depends on a registry setting.) Instead it’s a placeholder 
name by which the local names of the mapped network drives can be addressed. 
For example, the network drive \\BigSrur\DrvC could be mapped to the local name 
JoeBob. Files and directories on \\BigSrur\DrvC would appear under the folder 
\network\joebob. Since Windows CE doesn’t support drive letters, the local name 
can’t be specified in the form of a drive, as in G:. 

I mentioned that the \network folder is a virtual folder; this needs further ex- 
planation. Before Windows CE 2.1, the network folder wasn’t visible to the standard 
file system functions. If you use the FindFirstFile/FindNextFile process to enumerate 
the directories in the root directory, the \network directory won’t be enumerated. 
However, FindFirstFile/FindNextFile enumerates the mapped resources contained in 
the \network folder. So if the search string is \** to enumerate the root directory, 
the network isn’t enumerated, but if you use \network\*.* as the search string, any 
mapped drives will be enumerated. 

Starting with Windows CE 2.1, the \network folder can be enumerated by Find- 
FirstFile and FindNextFile if the proper registry settings are made. However, even 
though the folder can be enumerated, you still can’t place files or create folders within 
the \network folder. To make the \network folder visible, the DWORD value Register- 
FSRoot under the key [HKEY_LOCAL_MACHINE]\comm\redir, must be set to a non- 
zero value. 

The most direct way to map a remote resource is to call this function: 


DWORD WNetAddConnection3 (HWND hwndOwner, LPNETRESOURCE IpNetResource, 
LPTSTR lpPassword, LPTSTR 1pUserName, 
DWORD dwFlags); 


The first parameter is a handle to a window that owns any network support dialogs 
that might need to be displayed to complete the connection. The window handle can 
be NULL if you don’t want to specify an owner window. This effectively turns the 
WNetAddConnection3 function into the WNetAddConnection2 function supported 
under other versions of Windows. 


581 


Part Ill 


582 


The second parameter, /pNetResource, should point to a NETRESOURCE struc- 
ture that defines the remote resource being connected. The structure is defined as 


typedef struct _NETRESOURCE { 
DWORD dwScope; 
DWORD dwType; 
DWORD dwDisplayType; 
DWORD dwUsage; 
LPTSTR IpLocalName; 
LPTSTR IpRemoteName; 
LPTSTR 1pComment ; 
LPTSTR 1lpProvider; 

} NETRESOURCE; 


Most of these fields aren’t used for the WNetAddConnection3 function and should 
be set to 0. All you need to do is to specify the UNC name of the remote resource in 
a string pointed to by /pRemoteName and the local name in a string pointed to by 
lpLocalName. The local name is limited to 64 characters in length. The other fields in 
this structure are used by the WNet enumeration functions that I’ll describe shortly. 

You use the next two parameters in WNetAddConnection3, lpPassword and 
[pUserName, when requesting access from the server to the remote device. If you don’t 
specify a user name and Windows CE can’t find user information for network access 
already defined in the registry, the system displays a dialog box requesting the user 
name and password. Finally, the dwFlags parameter can be either 0 or the flag CON- 
NECT_UPDATE_PROFILE. When this flag is set, the connection is dubbed persistent. 
Windows CE stores the connection data for persistent connections in the registry. 
Unlike other versions of Windows, Windows CE doesn’t restore persistent connec- 
tions when the user logs on. Instead, the local name to remote name mapping is tracked 
only in the registry. If the local folder is later accessed after the original connection 
was dropped, a reconnection is automatically attempted when the local folder is 
accessed. 

If the call to WNetAddConnection3 is successful, it returns NO_ERROR. Unlike 
most Win32 functions, WNetAddConnection3 returns an error code in the return value 
if an error occurs. This is a nod to compatibility that stretches back to the Windows 
3.1 days. You can also call GetLastError to return the error information. As an aside, 
the function WNetGetLastError is supported under Windows CE in that it’s redefined 
as GetLastError, so you can call that function if compatibility with other platforms is 
important. | 

The other function you can use under Windows CE to connect a remote resource 
is WNetConnectionDialog1. This function presents a dialog box to the user request- 
ing the remote and local names for the connection. The function is prototyped as 


DWORD WNetConnectionDialogl (LPCONNECTDLGSTRUCT lIpConnectD1lgStruc) ; 
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The one parameter is a pointer to a CONNECTDLGSTRUCT structure defined as the 
following: 


typedef struct { 
DWORD cbStructure; 
HWND hwndOwner; 
LPNETRESOURCE 1pConnRes; 
DWORD dwFlags; 
DWORD dwDevNun; 

} CONNECTDLGSTRUCT; 


The first field in the structure is the size field and must be set with the size of 
the CONNECTDLGSTRUCT structure before you call WNetConnectionDialog1. The 
hwndOwner field should be filled with the handle of the owner window for the dia- 
log box. The JpConnRes field should point to a NETRESOURCE structure. This struc- 
ture should be filled with zeros except for the JpRemoteName field, which may be 
filled to specify the default remote name in the dialog. You can leave the JpRemoteName 
field 0 if you don’t want to specify a suggested remote path. 

The dwFlags field can either be 0 or set to the flag CONNDLG_RO_PATH. When 
this flag is specified, the user can’t change the remote name field in the dialog box. 
Of course, this means that the JpbRemoteName field in the NETRESOURCE structure 
must contain a valid remote name. Windows CE ignores the dwDevNum field in the 
CONNECTDLGSTRUCT structure. 

When the function is called, it displays a dialog box that allows the user to specify 
a local and, if not invoked with the CONNDLG_RO_PATH flag, the remote name as 
well. If the user taps on the OK button, Windows attempts to make the connection 
specified. The connection, if successful, is recorded as a persistent connection in the 
registry. 

If the connection is successful, the function returns NO_ERROR. If the user 
presses the Cancel button in the dialog box, the function returns —1. Other return 
codes indicate errors processing the function. 


Disconnecting a remote resource 
You can choose from three ways to disconnect a connected resource. The first method 
is to delete the connection with this function: 


DWORD WNetCancelConnection2 (LPTSTR IpName, DWORD dwFlags, 

BOOL fForce); 
The /pName parameter points to either the local name or the remote network name 
of the connection you want to remove. The dwFlags parameter should be set to 0 or 
CONNECT_UPDATE_PROFILE. If CONNECT_UPDATE_PROFILE is set, the entry in 
the registry that references the connection is removed; otherwise the call won’t change 
that information. Finally, the fForce parameter indicates whether the system should 
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continue with the disconnect, even if there are open files or print jobs on the remote 
device. If the function is successful, it returns NO_ERROR. 

You can prompt the user to specify a network resource to delete using this 
function: 


DWORD WNetDisconnectDialog (HWND hwnd, DWORD dwType); 


This function brings up a system provided dialog box that lists all connections cur- 
rently defined. The user can select one from the list and tap on the OK button to 
disconnect that resource. The two parameters for this function are a handle to the 
window that owns the dialog box and dwType, which is supposed to define the type 
of resources—printer (RESOURCETYPE_PRINT) or disk (RESOURCETYPE_DISK)— 
enumerated in the dialog box. However, some systems ignore this parameter and 
enumerate both disk and print devices. This dialog, displayed by WnetDisconnect- 
Dialog, is actually implemented by the network driver. So it’s up to each OEM to get 
this dialog to work correctly. 
A more specific method to disconnect a network resource is to call 


DWORD WNetDisconnectDialogl (LPDISCDLGSTRUCT IpDiscDlgStruc) ; 


This function is misleadingly named in that it won’t display a dialog box if all the 

parameters in DISCDLGSTRUCT are correct and point to a resource not currently 

being used. The dialog part of this function appears when the resource is being used. 
The DISCDLGSTRUCT is defined as 


typedef struct { 

- DWORD cbStructure; 
HWND hwndOwner; 
LPTSTR IpLocalName; 
LPTSTR ]pRemoteName; 
DWORD dwFlags; 

} DISCDLGSTRUCT; 


As usual, the cbStructure field should be set to the size of the structure. The hwnd- 
Owner field should be set to the window that owns any dialog box displayed. The 
IpLocalName and IpRemoteName fields should be set to the local and remote names 
of the resource that’s to be disconnected. Under current implementations, the 
IpLocalName is optional while the /pRemoteName field must be set for the function 
to work correctly. The dwFlags parameter can be either 0 or DISC_NO_FORCE. If this 
flag is set and the network resource is currently being used, the system simply fails 
the function. Otherwise, a dialog appears asking the user if he or she wants to dis- 
connect the resource even though the resource is being used. Under the current 
implementations, the DISC_NO_FORCE flag is ignored. 
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Enumerating network resources 
It’s all very well and good to connect to a network resource, but it helps if you know 
what resources are available to connect to. Windows CE supports three WNet func- 
tions used to enumerate network resources: WNetOpenEnum, WNetEnumResource, 
and WNetCloseEnum. The process is similar to enumerating files with FileFindFirst, 
FileFindNext, and FileFindClose. 

To start the process of numerating network resources, first call the function 


DWORD WNetOpenEnum (DWORD dwScope, DWORD dwType, DWORD dwUsage, 
LPNETRESOURCE lpNetResource, 
LPHANDLE 1phEnum) ; 


The first parameter dwScope specifies the scope of the enumeration. It can be one of 
the following flags: 


MM RESOURCE_CONNECTED Enumerate the connected resources. 
M RESOURCE_REMEMBERED Enumerate the persistent network connections. 
M jRESOURCE_GLOBALNET Enumerate all resources on the network. 


The first two flags, RESOURCE_CONNECTED and RESOURCE_REMEMBERED, 
simply enumerate the resources already connected on your machine. The difference 
is that RESOURCE_CONNECTED returns the network resources that are connected 
at the time of the call, while RESOURCE_REMEMBERED returns those that are per- 
sistent regardless of whether they’re currently connected. When using either of these 
flags, the dwUsage parameter is ignored and the /pNetResource parameters must 
be NULL. 

The third flag, RESOURCE_GLOBALNET, allows you to enumerate resources— 
such as servers, shared drives, or printers out on the network—that aren’t connected. 
The dwType parameter specifies what you’re attempting to enumerate—shared 
disks (RESOURCETYPE_DISK), shared printers (RESOURCETYPE_PRINT), or both 
(RESOURCETYPE_ANY). 

You use the third and fourth parameters only if the dwScope parameter is set to 
RESOURCE_GLOBALNET. The dwUsage parameter specifies the usage of the resource 
and can be 0 to enumerate any resource, RESOURCEUSAGE_CONNECTABLE to 
enumerate only connectable resources, or RESOURCEUSAGE_CONTAINER to enu- 
merate only containers such as servers. 

If the dwScope parameter is set to RESOURCE_GLOBALNET, the fourth param- 
eter, JpNetResource must point to a NETRESOURCE structure; otherwise the parameter 
must be NULL. The NETRESOURCE structure should be initialized to specify the starting 
point on the network for the enumeration. The starting point is specified by a UNC 
name in the jpRemoteName field of NETRESOURCE. The dwUsage field of the NET- 
RESOURCE structure must be set to RESOURCETYPE_CONTAINER. For example, to 
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enumerate the shared resources on the server BIGSERV the JpRemoteName field would 
point to the string \\BIGSERV. To enumerate all servers in a domain, the JpRemote- 
Name should simply specify the domain name. For the domain EntireNet, the 
lpRemoteName field should point to the string EntireNet. Because Windows CE 
doesn’t allow you to pass a NULL into JpRemoteName when you use the RESOURCE_ 
GLOBALNET flag, you can’t enumerate all resources in the network namespace 
as you can under Windows 98 or Windows NT. This restriction exists because 
Windows CE doesn’t support the concept of a Windows CE device belonging to a 
specific network context. 

The final parameter of WNetOpenEnum, IpbEnum, is a pointer to an enumera- 
tion handle that will be passed to the other functions in the enumeration process. 
WNetOpenEnum returns a value of NO_ERROR if successful. If the function isn’t suc- 
cessful, you can call GetLastError to query the extended error information. 

Once you have successfully started the enumeration process, you actually query 
data by calling this function: 


DWORD WNetEnumResource (HANDLE hEnum, LPDWORD IpcCount, 
LPVOID \ipBuffer, 
LPDWORD 1lpBufferSize) ; 


The function takes the handle returned by WNetOpenEnum as its first parameter. The 
second parameter is a pointer to a variable that should be initialized with the num- 
ber of resources you want to enumerate in each call to WNetEnumResource. You can 
specify a —1 in this variable if you want WNetEnumResource to return the data for as 
many resources as will fit in the return buffer specified by the (pBuffer parameter. 
The final parameter is a pointer to a DWORD that should be initialized with the size 
of the buffer pointed to by /pBuffer. If the buffer is too small to hold the data for even 
one resource, WNetEnumResource sets this variable to the required size for the buffer. 

The information about the shared resources returned by data is returned in the 
form of an array of NETRESOURCE structures. While this is the same structure I de- 
scribed when I talked about the WNetAddConnection3 function, I'll list the elements 
of the structure here again for convenience: 


typedef struct _NETRESOURCE { 
DWORD dwScope; 
DWORD dwType; 
DWORD dwDisplayType; 
DWORD dwUsage; 
LPTSTR 1pLocalName; 
LPTSTR 1pRemoteName; 
LPTSTR |1pComment ; 
LPTSTR IpProvider; 

} NETRESOURCE; 
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The interesting fields in the context of enumeration start with the dwType field, 
which indicates the type of resource that was enumerated. The value can be 
RESOURCETYPE_DISK or RESOURCETYPE_PRINT. The dwDisplayType field provides 
even more information about the resource, demarcating domains (RESOURCE- 
DISPLAYTYPE_ DOMAIN) from servers (RESOURCEDISPLAYTYPE_SERVER) and 
from shared disks and printers (RESOURCEDISPLAYTYPE_SHARE). A fourth flag, 
RESOURCEDISPLAYTYPE_GENERIC, is returned if the display type doesn’t matter. 

The /pLocalName field points to a string containing the local name of the 
resource if the resource is currently connected or is a persistent connection. The 
IpRemoteName field points to the UNC name of the resource. The Jp>Comment field 
contains the comment line describing the resource that’s provided by some servers. 

WNetEnumResource either returns NO_ERROR, indicating the function passed 
(but you need to call it again to enumerate more resources), or ERROR_NO_ 
MORE_ITEMS, indicating that you have enumerated all resources matching the speci- 
fication passed in WNetOpenEnum. With any other return code, you should call 
GetLastError to further diagnose the problem. 

You have few strategies when enumerating the network resources. You can 
specify a huge buffer and pass a —1 in the variable pointed to by /pcCount, telling 
WNetEnumResource to return as much information as possible in one shot. Or you 
can specify a smaller buffer and ask for only one or two resources for each call to 
WNetEnumResource. The one caveat on the small buffer approach is that the strings 
that contain the local and remote names are also placed in the specified buffer. The 
name pointers inside the NETRESOURCE structure then point to those strings. This 
means that you can’t specify the size of the buffer to be exactly the size of the 
NETRESOURCE structure and expect to get any data back. A third possibility is to 
call WNetEnumResource twice, the first time with the /pBuffer parameter 0, and have 
Windows CE tell you the size necessary for the buffer. Then you allocate the buffer 
and call WNetEnumResource again to actually query the data. However you use 
WnetEnumkResource, you'll need to check the return code to see whether it needs to 
be called again to enumerate more resources. 

When you have enumerated all the resources, you must make one final call to 
the function: 


DWORD WNetCloseEnum (HANDLE hEnum); 


The only parameter to this function is the enumeration handle first returned by 
WNetOpenEnum. This function cleans up the system resources used by the enumera- 
tion process. 

Following is a short routine that uses the enumeration functions to query the 
network for available resources. You pass to a function a UNC name to use as the 
root of the search. The function returns a buffer of zero-delimited strings that desig- 
nate the local name, if any, and the UNC name of each shared resource found. 
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// Helper routine 
int AddToList (LPTSTR *pPtr, INT *pnListSize, LPTSTR pszStr) { 
INT nLen = Istrlen (pszStr) + 1; 


if (*pnListSize < nLen) return -1; 
lstrcpy (*pPtr, pszStr); 

*pPtr += nLen; 

*pnListSize -= nLen; 

return Q; 


// EnumNetDisks - Produces a list of shared disks on a network 
// 
int EnumNetDisks (LPTSTR pszRoot, LPTSTR pszNetList, int nNetSize) { 
INT i = @, rc, nBuffSize = 1024; 
DWORD dwCnt, dwSize; 
HANDLE hEnum; 
NETRESOURCE nr; 
LPNETRESOURCE pnr; 
PBYTE pPtr, pNew; 


// Allocate buffer for enumeration data. 
pPtr = (PBYTE) LocalAlloc (LPTR, nBuffSize); 
if (!pPtr) 

return -1; 


// Initialize specification for search root. 
memset (&nr, 0, sizeof (nr)); 
nr.]pRemoteName = pszRoot; 

nr.dwUsage = RESOURCEUSAGE_CONTAINER; 


// Start enumeration. 
rc = WNetOpenEnum (RESOURCE_GLOBALNET, RESOURCETYPE_DISK, @, &nr, 
&hEnum) ; 
if (rc != NO_ERROR) 
return -1; 


// Enumerate one item per loop. 
do { 
dwCnt = 1; 
dwSize = nBuffSize; 
rc = WNetEnumResource (hEnum, &dwCnt, pPtr, &dwSize); 


// Process returned data. 
if (rc == NO_ERROR) { 
pnr = (NETRESOURCE *)pPtr; 
if (pnr->1pRemoteName) 
rc = AddToList (&pszNetList, &nNetSize, 
pnr->|lpRemoteName) ; 
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// If our buffer was too small, try again. 


} else if (rc == ERROR_MORE_DATA) { 
pNew = LocalReAlloc (pPtr, dwSize, LMEM_MOVEABLE) ; 
if (pNew) { 
pPtr = pNew; 
nBuffSize = LocalSize (pPtr); 
re = @; 
} 
} 


} while (re == Q); 


// If the loop was successful, add extra zero to list. 
if (rc == ERROR_NO_MORE_ITEMS) { 
rc = AddToList (&pszNetList, &nNetSize, TEXT ("")); 
re = Q; 
} 


// Clean up. 
WNetCloseEnum (hEnum) ; 
LocalFree (pPtr); 
return rc; 


While the enumeration functions work well to query what’s available on the 
net, you can use another strategy for determining the current connected resources. 
At the simplest level, you can use FileFindFirst and FileFindNext to enumerate the 
locally connected network disks by searching the folders in the \network directory. 
Once you have the local name, a few functions are available to you for querying just 
what that local name is connected to. 


Querying connections and resources 

The folders in the \network directory represent the local names of network shared 
disks that are persistently connected to network resources. To determine which of 
the folders are currently connected, you can use the function 


DWORD WNetGetConnection (LPCTSTR IpLocalName, 
LPTSTR 1pRemoteName, 
LPDWORD IpnLength) ; 


WNetGetConnection returns the UNC name of the network resource associated with 
a local device or folder. The JpLocalName parameter is filled with the local name of 
a shared folder or printer. The Jp>RemoteName parameter should point to a buffer that 
can receive the UNC name for the device. The JpnLength parameter points to a DWORD 
value that initially contains the length in characters of the remote name buffer. If the 
buffer is too small to receive the name, the length value is loaded with the number of 
characters required to hold the UNC name. 
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One feature (or problem, depending on how you look at it) of WNetGet- 
Connection is that it fails unless the local folder or device has a current connection to 
the remote shared device. This allows us an easy way to determine which local fold- 
ers are currently connected and which are just placeholders for persistent connec- 
tions that aren’t currently connected. | 

Sometimes you need to transfer a filename from one system to another and you 
need a common format for the filename that would be understood by both systems. 
The WNetGetUniversalName function translates a filename that contains a local net- 
work name into one using the UNC name of the connected resource. The prototype 
for WNetGetUniversalName is the following: 


DWORD WNetGetUniversalName (LPCTSTR IpLocalPath, DWORD dwInfoLevel, 
LPVOID IpBuffer, LPDWORD IpBufferSize); 


Like WNetGetConnection, this function returns a UNC name for a local name. There 
are two main differences between WNetGetConnection and WNetGetUniversalName. 
First, WNetGetUniversalName works even if the remote resource isn’t currently con- 
nected. Second, you can pass a complete filename to WNetGetUniversalName instead 
of simply the local name of the shared resource, which is all that is accepted by 
WNetGetConnection. 

WNetGetUniversalName returns the remote information in two different formats. 
If the dwInfoLevel parameter is set to UNIVERSAL_NAME_INFO_LEVEL, the buffer 
pointed to by pBuffer is loaded with the following structure: 


typedef struct _UNIVERSAL_NAME_INFO { 
LPTSTR IpUniversalName; 
} UNIVERSAL_NAME_INFO; 


The only field in the structure is a pointer to the UNC name for the shared resource. 
The string is returned in the buffer immediately following the structure. So, if a 
server \\BigServ\DriveC was attached as LocC and you pass WnetGetUniversalName 
the filename \network\LocC\win32\filename.ext, it returns the UNC name \\BigServ\ 
DriveC\win32\ filename.ext. 

If the dwinfoLevel parameter is set to REMOTE_NAME_INFO_LEVEL, the buffer 
is filled with the following structure: 


typedef struct _REMOTE_NAME_INFO 
LPTSTR IpUniversalName; 
LPTSTR IpConnectionName; 
LPTSTR JpRemainingPath; 

} REMOTE_NAME_INFO; 


This structure returns not just the UNC name, but also parses the UNC name into the 
share name and the remaining path. So, using the same filename as in the previous 
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example, \network\LocC\win32\filename.ext, the REMOTE_NAME_INFO fields 
would point to the following strings: 
lpUniveralName: \\BigServ\ DriveC\win32\filename.ext 
IpConnectionName: \\BigServ\DriveC 
IpkemainingPath:  \win32\filename.ext 


One more thing: you don’t have to prefix the local share name with \network. 
In the preceding example, the filename \LocC\Win32\filename.ext would have pro- 
duced the same results. 

One final WNet function supported by Windows CE is 


DWORD WnetGetUser (LPCTSTR IpName, LPTSTR IpUserName, 
LPDWORD lIpnLength); 


This function returns the name the system used to connect to the remote resource. 
WnetGetUser is passed the local name of the shared resource and returns the user 
name the system used when connecting to the remote resource in the buffer pointed 
to by /pUserName. The IpnLengh parameter should point to a variable that contains 
the size of the buffer. If the buffer isn’t big enough to contain the user name, the variable 
pointed to by /pnLength is filled with the required size for the buffer. 


The ListNet Example Program 


ListNet is a short program that lists the persistent network connections on a Windows CE 
machine. The program’s window is a dialog box with three controls: a list box that 
displays the network connections, a Connect button that lets you add a new persis- 
tent connection, and a Disconnect button that lets you delete one of the connections. 
Double-clicking on a connection in the list box opens an Explorer window to dis- 
play the contents of that network resource. Figure 10-1 shows the ListNet window 
while Figure 10-2 on the next page shows the ListNet source code. 
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Figure 10-1. Zhe ListNet window containing a few network folders. 
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WnetDisconnectDialog respectively. You open an Explorer window containing the 
shared network disk by launching EXPLORER.EXE with a command line that’s the 
path of the folder to open. 


BASIC SOCKETS 


WinSock is the name for the Windows socket API. WinSock is the API for Windows CE 
TCP/IP networking stack as well as the IrDA infrared communication stack. Win- 
dows CE implements a subset of WinSock version 1.1. What’s left out of the 
Windows CE implementation of WinSock is the ever-so-handy WSAAsyncSelect func- 
tion that enables Ginder other Windows systems) an application to be informed when 
a WinSock event occurred. Actually, most of the WSAxxx calls that provide asynchro- 
nous actions are missing from Windows CE. Instead, the Windows CE implementa- 
tion is more like the original “Berkeley” socket API. Windows CE’s developers decided 
not to support these functions to reduce the size of the WinSock implementation. These 
functions were handy, but not required because Windows CE is multithreaded. 

The lack of asynchronous functions doesn’t mean that you’re left with calling 
socket functions that block on every call. You can put a socket in nonblocking mode 
so that any function that can’t accomplish its task without waiting on an event will 
return with a return code indicating that the task isn’t yet completed. 

Windows CE has extended WinSock in one area. As I mentioned in Chapter 9, 
WinSock is also the primary interface for IrDA communication. To do this, Windows 
CE extends the socket addressing scheme, actually providing an entirely different 
addressing mode designed for the transitory nature of IrDA communication. 

In this section, I’m not going to dive into a complete explanation of socket-based 
communication. Instead, I'll present an introduction that will get you started com- 
municating with sockets. In addition, I’ll spend time with the IrSock side because this 
interface is so significant for Windows CE devices. 


Initializing the WinSock DLL 


Like other versions of WinSock, the Windows CE version should be initialized before 
you use it. You accomplish this by calling WSAStartup, which initializes the WinSock 
DLL. It’s prototyped as 


int WSAStartup (WORD wVersionRequested, LPWSADATA IpWSAData ); 


The first parameter is the version of WinSock you’re requesting to open. For all cur- 
rent versions of Windows CE, you must indicate version 1.1. An easy way to do this 
is to use the MAKEWORD macro as in MAKEWORD (1,1). The second parameter must 
point to a WSAData structure, shown in the code on the next page. 


599 


Part Ill 


600 


struct WSAData { 

WORD wVersion; 

WORD wHighVersion; 

char szDescription[WSADESCRIPTION_LEN+1]; 

char szSystemStatus[WSASYSSTATUS_LEN+1]; 

unsigned short iMaxSockets; 

unsigned short iMaxUdpDg; 

char FAR * 1pVendorInfo; 
}3 
This structure is filled in by WSAStartup, providing information about the specific 
implementation of this version of WinSock. Currently, the first two fields return 0x0107, 
indicating support for version 1.1. The szDescription and szSystemStatus fields can 
be used by WinSock to return information about itself. In the current Windows CE 
version of WinSock, these fields aren’t used. The iMaxSockets parameter suggests a 
maximum number of sockets that an application should be able to open. This num- 
ber isn’t a hard maximum but more a suggested maximum. Finally, the iMaxUdpDg 
field indicates the maximum size of a datagram packet. A 0 indicates no maximum 
size for this version of WinSock. 

WSAStartup returns 0 if successful; otherwise the return value is the error code 
for the function. Don’t call WSAGetLastError in this situation because the failure of 
this function indicates that WinSock, which provides WSAGetLastError, wasn’t initial- 
ized correctly. 

Windows CE also supports WSACleanup, which is traditionally called when an 
application has finished using the WinSock DLL. For Windows CE, this function per- 
forms no action but is provided for compatibility. Its prototype is 


int WSACleanup (); 


ASCII vs. Unicode 
One issue that you'll have to be careful of is that almost all the string fields used in 
the socket structures are char fields, not Unicode. Because of this, you'll find your- 
self using the functions 


int WideCharToMultiByte(UINT CodePage, DWORD dwFlags, 
LPCWSTR I}pWideCharStr, int cchWideChar, 
LPSTR IpMultiByteStr, int cchMultiByte, 
LPCSTR IpDefaultChar, LPBOOL IpUsedDefaultChar); 


to convert Unicode strings into multibyte strings and 


int MultiByteToWideChar (UINT CodePage, DWORD dwFlags, 
LPCSTR IpMultiByteStr, int cchMultiByte, 
LPWSTR I]pWideCharStr, int cchWideChar); 


to convert multibyte characters into Unicode. The functions refer to multibyte 
characters instead of ASCII because on double-byte coded systems, they convert 
double-byte characters into Unicode. 
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Stream Sockets 


Like all socket implementations, WinSock under Windows CE supports both stream 
and datagram connections. In a stream connection, a socket is basically a data pipe. 
Once two points are connected, data is sent back and forth without the need for 
additional addressing. In a datagram connection, the socket is more like a mailslot, 
with discrete packets of data being sent to specific addresses. In describing the 
WinSock functions, I’m going to cover the process of a creating a stream connec- 
tion (sometimes called a connection-oriented connection) between a client and 
server application. I'll leave explanation of the datagram connection to other, more 
network-specific books. 

The life of a stream socket is fairly straightforward: it’s created, bound, or con- 
nected to an address; read from or written to; and finally closed. A few extra steps 
along the way, however, complicate the story slightly. Sockets work in a client/server 
model. A client initiates a conversation with a known server. The server, on the other 
hand, waits around until a client requests data. When setting up a socket, you have 
to approach the process from either the client side or the server side. This decision 
determines which functions you call to configure a socket. Figure 10-3 illustrates the 
process from both the client and the server side. For each step in the process, the 
corresponding WinSock function is shown. 


Server Function Client Function 

Create socket socket Create socket socket 

Bind socket to an address bind Find desired server (many functions) 
Listen for client connections listen Connect to server connect 

Accept client’s connection accept 

Receive data from client recv Send data to server send 

Send data to client send Receive data from server = recv 


Figure 10-3. Zhe process for producing a connection-oriented socket connection. 


Both the client and the server must first create a socket. After that, the process 
diverges. The server must attach, or to use the function name, bind, the socket to an 
address so that another computer or even a local process, can connect to the socket. 
Once an address has been bound, the server configures the socket to listen for a 
connection from a client. The server then waits to accept a connection from a client. 
Finally, after all this, the server is ready to converse. 

The client’s job is simpler: the client creates the socket, connects the socket to 
a remote address, and then sends and receives data. This procedure, of course, 
ignores the sometimes not-so-simple process of determining the address to connect 
to. Pll leave that problem for a few moments while I talk about the functions behind 
this process. 
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Creating a socket 
You create a socket with the function 


SOCKET socket (int af, int type, int protocol); 


The first parameter, af, specifies the addressing family for the socket. Windows CE 
supports two addressing formats; AF_INET and AF_IRDA. You use the AF_IRDA con- 
stant when you’re creating a socket for IrDA use, and you use AF_INET for TCP/IP 
communication. The type parameter specifies the type of socket being created. For a 
TCP/IP socket, this can be either SOCK_STREAM for a stream socket or SOCK_DGRAM 
for a datagram socket. For IrDA sockets, the type parameter must be SOCK_STREAM. 
Windows CE doesn’t currently expose a method to create a raw socket, which is a 
socket that allows you to interact with the IP layer of the TCP/IP protocol. Among 
other uses, raw sockets are used to send an echo request to other servers, in the pro- 
cess known as pinging. However, Windows CE does provide a method of sending 
an ICMP echo request. I'll talk about that shortly. 

The protocol parameter specifies the protocol used by the address family speci- 
fied by the af parameter. The function returns a handle to the newly created socket. 
If an error occurs, the socket returns INVALID_SOCKET. You can call WSAGetLastError 
to query the extended error code. 


Server side: binding a socket to an address 
For the server, the next step is to bind the socket to an address. You accomplish this 
with the function 


int bind (SOCKET s, const struct sockaddr FAR *addr, int namelen); 


The first parameter is the handle to the newly created socket. The second parameter 
is dependent on whether you’re dealing with a TCP/IP socket or an IrDa socket. For 
a standard TCP/IP socket, the structure pointed to by addr should be SOCKADDR_IN, 
which is defined as 


struct sockaddr_in { 

short sin_family; 

unsigned short sin_port; 

IN_ADDR sin_addr; 

char sin_zero[8]; 
i 
The first field, sin_family must be set to AF_INET. The second field is the IP port while 
the third field specifies the IP address. The last field is simply padding to fit the stan- 
dard SOCKADDER structure. The last parameter of bind, namelen, should be set to 
the size of the SOCKADDR_IN structure. 

When you're using IrSock, the address structure pointed to by sockaddr is 
SOCKADDR_IRDA, which is defined as 
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struct sockaddr_irda { 

u_short irdaAddressFamily; 

u_char irdaDeviceID[4]; 

char irdaServiceName[25]; 
hs 
The first field, inrdaAddressFamily, should be set to AF_IRDA to identify the struc- 
ture. The second field, irdaDevicelD, is a 4-byte array that defines the address for 
this IR socket. This can be set to 0 for an IrSock server. The last field should be set to 
a string to identify the server. 

You can also use a special, predefined name in the irdaServiceName field to 
bypass the IrDA address resolution features. If you specify the name LSAP-SELxxx 
where xxx is a value from 001 through 127, the socket will be bound directly to the 
LSAP (Logical Service Assess Point) selector defined by the value. Applications should 
not, unless absolutely required, bind directly to a specific LSAP selector. Instead, by 
specifying a generic string, the IrDA Address resolution code determines a free LSAP 
selector and uses it. 


Listening for a connection 

Once a socket has been bound to an address, the server places the socket in listen 
mode so that it will accept incoming communication attempts. You place the socket 
in listen mode by using the aptly named function 


int listen (SOCKET s, int backlog); 


The two parameters are the handle to the socket and the size of the queue that you’re 
creating to hold the pending connection attempts. This value can be set to SOMAX- 
CONN to set the queue to the maximum supported by the socket implementation. 
For Windows CE, the only supported queue sizes are 1 and 2. Values outside this range 
are rounded to the closest valid value. 


Accepting a connection 
When a server is ready to accept a connection to a socket in listen mode, it calls this 
function: 


SOCKET accept (SOCKET s, struct sockaddr FAR «addr, 
int FAR *addrilen); 


The first parameter is the socket that has already been placed in listen mode. The 
next parameter should point to a buffer that receives the address of the client socket 
that has initiated a connection. The format of this address is dependent on the proto- 
col used by the socket. For Windows CE, this is either a SOCKADDR_IN or a SOCK- 
ADDR_IRDA structure. The final parameter is a pointer to a variable that contains the 
size of the buffer. This variable is updated with the size of the structure returned in 
the address buffer when the function returns. 
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The accept function returns the handle to a new socket that’s used to commu- 
nicate with the client. The socket that was originally created by the call to socket will 
remain in listen mode, and can potentially accept other connections. If accept de- 
tects an error, it returns INVALID_SOCKET. In this case, you can call WSAGetLastError 
to get the error code. 

The accept function is the first function I’ve talked about so far that blocks. That 
is, it won’t return until a remote client requests a connection. You can set the socket 
in nonblocking mode so that, if no request for connection is queued, accept will re- 
turn INVALID_SOCKET with an extended error code of WSAEWOULDBLOCK. Pll talk 
about blocking vs. nonblocking sockets shortly. 


Client side: connecting a socket to a server 
On the client side, things are different. Instead of calling the bind and accept func- 
tions, the client simply connects to a known server. I said simply, but as with most 
things, we must note a few complications. The primary one is addressing—knowing 
the address of the server you want to connect to. I'll put that topic aside for a mo- 
ment and assume the client knows the address of the server. 

To connect a newly created socket to a server, the client uses the function 


int connect (SOCKET s, const struct sockaddr FAR #*name, 
int namelen): 


The first parameter is the socket handle that the client created with a call to socket. 
The other two parameters are the address and address length values we’ve seen in 
the bind and accept functions. Here again, Windows CE supports two addressing 
formats: SOCKADDR_IN for TCP/IP—based communication and SOCKADDR_IRDA 
for IrDA communication. 7 

If connect is successful, it returns 0. Otherwise it returns SOCKET_ERROR, and 
you should call WSAGeiLastError to get the reason for the failure. 


Sending and receiving data 
At this point, both the server and client have socket handles they can use to commu- 
nicate with one another. The client uses the socket originally created with the call to 
socket, while the server uses the socket handle returned by the accept function. 

All that remains is data transfer. You write data to a socket this way: 


int send (SOCKET s, const char FAR *buf, int len, int flags); 


The first parameter is the socket handle to send the data. You specify the data you 
want to send in the buffer pointed to by the buf parameter while the length of that 
data is specified in Jen. The flags parameter must be 0. 

You receive data by using the function 


int recv (SOCKET s, char FAR «buf, int len, int flags); 
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The first parameter is the socket handle. The second parameter points to the buffer 

that receives the data, while the third parameter should be set to the size of the buffer. 

The flags parameter can be 0, or it can be MSG_PEEK if you want to have the current 

data copied into the receive buffer but not removed from the input queue or if this is 

a TCP/IP socket (MSG_OOB) for receiving any out-of-band data that has been sent. 
Two other functions can send and receive data; they are the following: 


int sendto (SOCKET s, const char FAR *buf, int len, int flags, 
const struct sockaddr FAR *to, int token); 


and 


int recvfrom (SOCKET s, char FAR *buf, int len, int flags, 
struct sockaddr FAR *from, int FAR *«fromlen); 


These functions enable you to direct individual packets of data using the address 
parameters provided in the functions. They’re used for connectionless sockets, but I 
mention them now for completeness. When used with connection-oriented sockets 
such as those I’ve just described, the addresses in sendto and recufrom are ignored 
and the functions act like their simpler counterparts, send and recv. 


Closing a socket 
When you have finished using the sockets, call this function: 


int shutdown (SOCKET s, int how); 


The shutdown function takes the handle to the socket and a flag indicating what part 
of the connection you wish to shut down. The How parameter can be SD_RECEIVE 
to prevent any further recv calls from being processed, SD_SEND to prevent any fur- 
ther send calls from being processed, or SD_BOTH to prevent either send or recu calls 
from being processed. The shutdown function affects the higher level functions send 
and recv but doesn’t prevent data previously queued from being processed. Once 
you have shut down a socket, it can’t be used again. It should be closed and a new 
socket created to restart a session. 

Once a connection has been shut down, you should close the socket with a 
call to this function: 


int closesocket (SOCKET s); 


The action of closesocket depends on how the socket is configured. If you’ve prop- 
erly shut down the socket with a call to shutdown, no more events will be pending 
and closesocket should return without blocking. If the socket has been configured 
into “linger” mode and configured with a timeout value, closesocket will block until 
any data in the send queue has been sent or the timeout expires. 
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I’ve alluded to IrSock a number of times as I’ve described functions. IrSock is essen- 
tially a socketlike API built over the top of the IrDA stack used for infrared commu- 
nication. IrSock is the only high-level interface to the IrDA stack. Even the Ircomm 
virtual comm port described in Chapter 9 uses the IrSock API underneath the covers. 

The major differences between IrSock and WinSock are that IrSock doesn’t 
support datagrams, it doesn’t support security, and the method used for addressing it 
is completely different from that used for WinSock. What IrSock does provide is a 
method to query the devices ready to talk across the infrared port, as well as arbitra- 
tion and collision detection and control. 

From a programmer’s perspective, the main difference in programming IrSock 
and WinSock is that the client side needs a method of detecting what infrared ca- 
pable devices are within range and are ready to accept a socket connection. This is 
accomplished by calling getsockopt with the level parameter set to SOL_IRLMP and 
the optname parameter set to IRLMP_ENUMDEVICES, as in the following: 


dwBuffSize = sizeof (buffer); 
rc = getsockopt (hIrSock, SOL_IRLMP, IRLMP_ENUMDEVICES, 
buffer, &dwBuffSize); 


When called with IRLMP_ENUMDEVICES, getsockopt returns a DEVICELIST structure 
in the buffer. DEVICELIST is defined as 


typedef struct _DEVICELIST { 
ULONG numDevice; 
IRDA_DEVICE_INFO Device[1]; 
} DEVICELIST; 


The DEVICELIST structure is simply a count followed by an array of IRDA_DE- 
VICE_INFO structures, one for each device found. The IRDA_DEVICE_INFO struc- 
ture is defined as 


typedef struct _IRDA_DEVICE_INFO { 
u_char irdaDeviceID[4]; 
char irdaDeviceName[22]; 
u_char Reserved[2]; 

} IRDA_DEVICE_INFO; 


The two fields in the IRDA_DEVICE_INFO structure are a device ID and a string that 
can be used to identify the remote device. 

Following is a routine that opens an IR socket and uses getsockopt to query the 
remote devices that are in range. If any devices are found, their names and IDs are 
printed to the debug port. 
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// 

// Poll for IR devices. 

Li 

DWORD WINAPI IrPoll (HWND hWnd) { 
INT PC, NSITZ6 2. 142-93 
char cDevice[256]; 
TCHAR szName[32], szOut[256]; 
DEVICELIST *pDL; 
SOCKET irsock; 


// Open an infrared socket. 
irsock = socket (AF_IRDA, SOCK_STREAM, @); 
if (irsock == INVALID_SOCKET) 

return -1; 


// Search for someone to talk to, try 10 times over 5 seconds. 
for (i = @; i < 10; i++) { 


// Call getsockopt to query devices. 
memset (cDevice, ®, sizeof (cDevice)); 
nSize = sizeof (cDevice); 
re = getsockopt (irsock, SOL_IRLMP, IRLMP_ENUMDEVICES, 
cDevice, &nSize); 
if (rc) 
break; 


pDL = (DEVICELIST *) cDevice; 
if (pDL->numDevice) { 
Add2List (hWnd, TEXT ("4d devices found."), pDL->numDevice); 


for (j = 0; j < Cint)pDL->numDevice; j++) { 

// Convert device ID. 

wsprintf (szOut, 
TEXT ("DevicelID \t%@2X.%02X .%02X .%02X"), 
pDL->DeviceLj].irdaDevicelID[Q], 
pDL->Device[j].irdaDe'viceID[1], 
pDL->Device[j].irdaDevicelID[2], 
pDL->Device[j].irdaDeviceID[3]); 

OutputDebugString (szOut); 


// Convert device name to Unicode. 

mbstowcs (szName, pDL->Device[j].irdaDeviceName, 
sizeof (pDL->Device[j].irdaDeviceName) ); 

wsprintf (szOut, TEXT ("irdaDeviceName \t%s"), 


szName) ; 
OutputDebugString (szOut); 


(continued) 


607 


Part Ill 


Sleep (500) ; 


} 
closesocket (irsock); 
return Q; 


Just having a device with an IR port in range isn’t enough; the remote device 
must have an application running that has opened an IR socket, bound it, and placed 
it into listen mode. This requirement is appropriate because these are the steps 
any server using the socket API would perform to configure a socket to accept 


communication. 
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Querying and setting IR socket options 
IrSock supports the getsockopt and setsockopt functions for getting and setting the 
socket options, but the options supported have little overlap with the socket options 
supported for a standard TCP/IP socket. To query socket options, use this function: 
int getsockopt (SOCKET s, int level, int optname, 
char FAR *optval, int FAR *optlen); 

The first parameter is the handle to the socket while the second parameter is the level 
in the communications stack for the specific option. The level can be at the socket 
level SO_SOCKET or a level unique to IrSock, SOL_LIRLMP. The options supported 
for IrSock are shown in the lists below. 

For the SOL_SOCKET level, your option is 


Mm SO_LINGER It queries the linger mode. 
For the SOL_IRLMP level, your options are 


MM JRLMP_ENUMDEVICES which enumerate remote IrDA devices 
IRIMP_IAS_QUERY which queries IAS attributes 


M JRILMP_SEND_PDU_LEN which queries the maximum size of send packet 
for IrLPT mode. 


The corresponding function with which to set the options is 


int setsockopt (SOCKET s, int level, int optname, 
const char FAR *optval, int optlen); 


The parameters are similar to getsockopt. The allowable options are shown below. 
For the SOL_SOCKET level, your option is 


M = SO_LINGER which delays the close of a socket if unsent data remains in 
the outgoing queue 
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For the SOL_IRLMP level, your options are 


M JIRIMP_IAS_SET which sets IAS attributes 

M %JIRLMP_IRLPT_MODE which sets the IrDA protocol to IrLPT 

M JRLMP_9WIRE_MODE which sets the IrDA protocol to 9-wire serial mode 
M JIRIMP_SHARP_MODE which sets the IrDA protocol to Sharp mode 


Blocking vs. nonblocking sockets 

One issue I briefly touched on as I was introducing sockets is blocking. Windows 
programmers are used to the quite handy asynchronous socket calls that are an ex- 
tension of the standard Berkeley socket API. By default, a socket is in blocking mode 
so that, for example, if you call recuv to read data from a socket and no data 
is available, the call blocks until some data can be read. This isn’t the type of call 
you want to be making with a thread that’s servicing the message loop for your 
application. 

Although Windows CE doesn’t support the WSAAsync calls available to desk- 
top versions of Windows, you can switch a socket from its default blocking mode to 
nonblocking mode. In nonblocking mode, any socket call that might need to wait 
to successfully perform its function instead returns immediately with an error code 
of WSAEWOULDBLOCK. You are then responsible for calling the would-have-blocked 
function again at a later time to complete the task. 

To set a socket into blocking mode, use this function: 


int ioctlsocket (SOCKET s, long cmd, u_long *argp); 


The parameters are the socket handle, a command, and a pointer to a variable that 
either contains data or receives data depending on the value in cmd. The allowable 
commands for Windows CE IrSock sockets are the following: 


@ FIONBIO Set or clear a socket’s blocking mode. If the value pointed to 
by argp is nonzero, the socket is placed in blocking mode. If the value is 
zero, the socket is placed in nonblocking mode. 


M FIONREAD Returns the number of bytes that can be read from the socket 
with one call to the recv function. 
So to set a socket in blocking mode, you should make a call like this one: 


fBlocking = FALSE; 
re = ioctlsocket (sock, FIONBIO, &fBlocking); 


Of course, once you have a socket in nonblocking mode, the worst thing you 
can do is continually poll the socket to see if the nonblocked event occurred. On a 


609 


Part Ill 


610 


battery-powered system, this can dramatically lower battery life. Instead of polling, 
you can use the select function to inform you when a socket or set of sockets is in a 
nonblocking state. The prototype for this function is 


int select (int nfds, fd_set FAR *readfds, fd_set FAR «writefds, 
fd_set FAR *exceptfds, 
const struct timeval FAR *timeout); 


The parameters for the select function look somewhat complex, which, in fact, they 
are. Just to throw a curve, the function ignores the first parameter. The reason it ex- 
ists at all is for compatibility with the Berkeley version of the select function. The next 
three parameters are pointers to sets of socket handles. The first set should contain 
the sockets that you want to be notified when one or more of the sockets is in a 
nonblocking read state. The second set contains socket handles of sockets that you 
want informed when a write function can be called without blocking. Finally, the third 
set, pointed to by exceptfds, contains the handles of sockets that you want notified 
when an error condition exists in that socket. 

The final parameter is a timeout value. In keeping with the rather interesting 
parameter formats for the select function, the timeout value isn’t a simple millisecond 
count. Rather, it’s a pointer to a TIMEVAL structure defined as 


struct timeval { 
long tv_sec; 
long tv_usec; 
3; 


If the two fields in TIMEVAL are 0, the select call returns immediately even if none of 
the sockets has had an event occur. If the pointer, timeout, is NULL instead of point- 
ing to a TIMEVAL structure, the select call won’t time out and returns only when an 
event occurs in one of the sockets. Otherwise, the timeout value is specified in sec- 
onds and microseconds in the two fields provided. 

The function returns the total number of sockets for which the appropriate events 
occur, 0 if the function times out, or SOCKET_ERROR if an error occurred while pro- 
cessing the call. If an error does occur, you can call WSAGetLastError to get the error 
code. The function modifies the contents of the sets so that, on returning from the 
function, the sets contain only the socket handles of sockets for which events occur. 

The sets that contain the events should be considered opaque. The format 
of the sets doesn’t match their Berkeley socket counterparts. Each of the sets is 
manipulated by four macros defined in WINSOCK.H. These are the four macros: 


mM FD_CIR Removes the specified socket handle from the set 
M FD_ISSET Returns true if the socket handle is part of the set 
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M FD_SET Adds the specified socket handle to the set 
M FD_ZERO Initializes the set to 0 


To use a set, you have to declare a set of type fd_set. Then initialize the set with 
a call to FD_ZERO and add the socket handles you want with FD_SET. An example 
would be 


fd_set fdReadSocks; 


FD_ZERO (&fdReadSocks); 
FD_SET (hSockl, &fdReadSocks); 
FD_SET (hSock2, &fdReadSocks); 


re = select (0, &fdReadSocks, NULL, NULL, NULL); 
if (re != SOCKET_ERROR) { 
if (FD_ISSET (hSockl, &fdReadSocks) ) 
// A read event occurred in socket 1. 
if (FD_ISSET (hSock2, &fdReadSocks) ) 
// A read event occurred in socket 2. 


In this example, the select call waits on read events from two sockets with handles 
of bSock1 and hSock2. The write and error sets are NULL as is the pointer to the timeout 
structure, so the call to select won’t return until a read event occurs in one of the two 
sockets. When the function returns, the code checks to see if the socket handles are 
in the returned set. If so, that socket has a nonblocking read condition. 

The last little subtlety concerning the select function is just what qualifies as a 
read, write, and error condition. A socket in the read set is signaled when one of the 
following events occur: 


M There is data in the input queue so that recv can be called without 
blocking. 


M@ The socket is in listen mode and a connection has been attempted so that 
a call to accept won't block. 


M ‘The connection has been closed, reset, or terminated. If the connection 
was gracefully closed, recv returns with 0 bytes read; otherwise the recv 
call returns SOCKET_ERROR. If the socket has been reset, the recu func- 
tion returns the error WSACONNRESET. 


A socket in the write set is signaled under the following conditions: 


M Data can be written to the socket. A call to send still might block if you 
attempt to write more data than can be held in the outgoing queue. 
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mM A socket is processing a connect and the connect has been accepted by 
the server. 


A socket in the exception set is signaled under the following condition: 


mM A socket is processing a connect and the connect failed. 


The MySqurt Example Program 


To demonstrate IrSock, the following program, MySqurt, shows how to transfer files 
from one Windows CE device to another. It’s similar to the IrSquirt program provided 
with the H/PC and Palm-size PC. The difference is that instead of sending a file across 
the infrared link and having the receiving side accept whatever file is sent, MySqurt 
has the receiving side specify the file that’s sent from the serving side of the applica- 
tion. In addition, MySqurt has a window that displays a list of status messages as the 
handshaking takes place between the two Windows CE systems. To use MySqurt, you'll 
need to have it running on both the Windows CE systems. To transfer a file, enter the 
name of the file you want from the other system and tap on the Get File button. The 
system transmits the request to the system and, if the file exists, it will be sent back to 
the requesting system. The MySqurt window is shown in Figure 10-4. The source code 
for the example is shown in Figure 10-5. 


. MySqurt 


ceived file size of 6144 bytes 
free space of 5602460 bytes 
Sending size ack, 
recy'd 2048 bytes. 
recy'd 2048 bytes. 
recy'd 2048 bytes, 


Figure 10-4. The MySqurt window after a file has been transferred. 


Figure 10-5. The MySqurt source. 
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From a Windows standpoint, MySqurt is a simple program. It uses a dialog box 
as its main window. When the program is first launched, it creates the server thread 
that creates an infrared socket, binds it to a service name, puts the socket into listen 
mode, and blocks on a call to accept. When a remote device connects, the server thread 
creates another thread to handle the actual sending of the file while it loops back 
and waits for another connection. 

The sender thread reads the filename from the client, opens the file, and attempts 
to send the file to the client device. Once the file is sent, the sender thread closes its 
socket and terminates. To support the transfer, a minimal amount of handshaking takes 
place. The sender thread sends the size of the file or an error code if the file can’t be 
opened. The client then responds with an acknowledgment that the file size is ac- 
ceptable and that the send can take place. The actual sending of the data is broken 
down into blocks arbitrarily set at 2048 bytes. After each block is sent, the sender 
thread waits for an acknowledgment from the client before it sends the next block. 

On the client side, a transmission is initiated when the user taps the Get File 
button. If text exists in the edit box, it is read and the GetFile routine is called. In this 
routine, a socket is created and any remote devices are enumerated using repeated 
calls to getsockopt. If a device is found, a connection is attempted with a call to con- 
nect. Connect succeeds only if the remote device has bound an IR socket using the 
same service name, which happens to be defined as the string contained in chzApp- 
Name, an ASCII representation of the program name. This addressing scheme ensures 
that if a connection is made, the remote device is running MySqurt. Once a connec- 
tion is made, the client sends over the filename it wants. This is actually done in two 
steps: first the byte length of the filename is sent, followed by the name itself. This 
process allows the server to know how many characters to receive before continu- 
ing. If the file sent by the server device fits in the object store, the routine creates the 
file on the client side, notifying the user if the file already exists. If all has gone well 
to this point, the data is received and written to the file. The socket is closed, and the 
buffer created to read the data into is freed. 

While I’ve spent most of the explanation of sockets focused on IrSock, one area 
of the TCP/IP WinSock is unique to Windows CE—the ICMP functions. These func- 
tions allow a “back door” that allows raw socketlike functions on a stack that doesn’t 
support raw sockets. Let’s look now at why that’s useful. 


P/IP PINGING 


On a TCP/IP network, there’s no more basic diagnostic than to ping a site. Pinging is 
the process of sending a request to a TCP/IP server to respond with an acknowledg- 
ment back to the sender. If you look at the source code for a ping utility, you'll see 
that pinging is simply the process of sending a specific type of IP packet to the re- 
quested server and waiting for a reply. 
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The format of these packets is defined by ICMP. ICMP stands for Internet Con- 
trol Message Protocol. This a protocol used by routers and servers on TCP/IP networks 
to report errors and status information. While most of this work goes unseen by ap- 
plications because it’s handled at the IP layer of the network stack, ping requests take 
place at this level. 

Under most systems, an application would have to open a raw socket. While 
Windows CE’s version of WinSock doesn’t expose a way of opening raw sockets, 
Windows CE gives you a few functions that encapsulate the process of pinging an- 
other server. 

Windows CE supports three functions that allow Windows CE applications to 
ping Internet addresses. Essentially, a Windows CE application opens a handle, sends 
the ICMP request as many times as you want, and closes the handle. While the func- 
tions are documented in the Windows CE SDK, the include files that define these 
prototypes aren’t in all versions of the Windows CE SDK. The file ICMPAPI.H con- 
tains the function prototypes while IPEXPORTS.H contains the definitions for the 
packet structures and constants used at the IP layer. These two include files are on 
the CD-ROM included with this book. 

To start the process, you must open an ICMP handle using this function: 


HANDLE IcmpCreateFile (VOID); 


The function takes no arguments and returns a handle that will be used in the 
other ICMP functions. If the function fails, the return value will be INVALID_ 
HANDLE_VALUE. 

To actually send a ping request, you use this function: 


DWORD WINAPI IcmpSendEcho (HANDLE IcmpHandle, IPAddr DestinationAddress, 
LPVOID RequestData, WORD RequestSize, 
PIP_OPTION_INFORMATION RequestOptions, 
LPVOID ReplyBuffer, DWORD ReplySize, 
DWORD Timeout); 


The first parameter is the handle returned by the JCMPCreateFile function. The sec- 
ond parameter is the destination address that will be sent to the IP packet. The data 
type for this address, [PAddr, is essentially an unsigned long value with the four bytes 
of the IP address packed inside. The RequestData parameter is a pointer to a buffer 
containing the data to be sent while the RequestSize parameter should specify the 
size of the data. You can define any data you want in the buffer pointed to by 
RequestData although you generally don’t want to exceed the 8-KB packet size limit 
found on some TCP/IP systems. What you do not get to do is directly define the ICMP 
packet that’s sent. That packet is automatically formed by JcmpSendEcho and sent 
along with the data specified in the RequestData buffer. 
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The RequestOptions parameter should point to an IP_LOPTION_INFORMATION 
structure that’s defined as 


Typedef struct ip_option_information { 


unsigned char Ttl; 
unsigned char Tos; 
unsigned char Flags; 
unsigned char OptionsSize; 


unsigned char FAR *«OptionsData; 
} IP_OPTION_INFORMATION; 


The data in this structure will be used by the function to fill in some of the IP packet 
header that you use when sending an ICMP packet. The structure is a subset of the 
IP packet structure since Windows CE takes care of things like computing checksums 
and the like. The formal definitions of these fields are best left to texts that explain 
the IP protocol in detail. What follows is a quick overview. 

The first field, Tt/, is the “Time to Live” for the packet. If the packet isn’t received 
in this amount of time, it will be dropped. The Tos field defines the type of service 
for the IP packet. The Flags field contains the flags for the IP header. Finally, the 
OptionsData and OptionsSize fields specify the IP packet options. The options are 
defined as bytes in the buffer pointed to by OptionsData. The OptionsSize field should 
contain the number of bytes in the OptionsData buffer. The format of the options 
buffer is defined by the IP protocol. 

The next two parameters in IcmpSendEcho are the pointer to the buffer that 
receives the reply and the size of that buffer. The receiving buffer must be large enough 
to hold an ICMP_ECHO_REPLY structure plus the size of the data you specified in 
the RequestData buffer. At a minimum, you must specify the buffer to be the size of 
ICMP_ECHO_REPLY plus 8 bytes. The 8-byte allowance is the size of an ICMP error 
message. 

The final parameter is Timeout, which is the time, in milliseconds, that Icmp- 
SendEcho waits for returning packets before giving up. 

IcmpSendEcho returns the number of reply packets received in response to the 
ping request. If the return value is 0, an error occurred. In this case, you should call 
GetLastError to receive the error code. 

The data received by IcmpSendEcho is in the form of an array of ICMP_ECHO- 
_REPLY structures, one from each router or server that replied to the original packet. 
Following the array will be the data sent out by IcmpSendEcho that returns with each 
of the packets. The ICMP_ECHO_REPLY structure is defined as 


struct icmp_echo_reply { 


IPAddr Address; // Replying address 
unsigned long Status; // Reply IP_STATUS 

unsigned long RoundTripTime; // RTT in milliseconds 
unsigned short DataSize; // Reply data size in bytes 
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unsigned short Reserved; // Reserved for system use 
void FAR Data; // Pointer to the reply data 
struct IP_OPTION_INFORMATION Options; // Reply options 


+; /* icmp_echo_reply */ 


The Address field is the TCP/IP address of the responding router or server. The 
address is in IPAddr format. The Status field contains the status returned by the re- 
sponding server. If the ping was successful, this field will contain IP_SUCCESS. Other 
values indicate errors and are defined in IPEXPORT.H. The RoundTripTime field 
contains the elapsed time, in milliseconds, from when the original packet was sent 
until the packet from this server was received. The DataSize field contains 
the size of the data returned by the server. This value should match the size of the 
data originally sent. The Data field contains a pointer to the data returned by the 
server. This data should match the data originally sent. Finally, the Options field is an 
IP_OPTION_INFORMATION structure that defines the details of the responding packet. 

Generally, you'll call JcompSendEcho a number of times to ping a site and then 
clean up with a call to IcmpCloseHandle. This function is prototyped as 


BOOL WINAPI IcmpCloseHandle (HANDLE IcmpHandle); 


The only parameter is the handle that was received with IcmpCreateFile. 

The routine below implements a very basic ping. The routine calls JcmpOpen 
and then fills in the IP packet data and calls IcmpSendEcho five times. The address 
passed to PingAddress is a Unicode string in Internet dot format, as in 123.45.56.78. 
The inet_addr function translates this into a DWORD value used by IcmpSendEcho. 
Notice that the address string passed to PingAddress is first translated into ASCII be- 
fore the call is made to inet_addr. 


// PingAddress - Ping a TCP/IP address. 
// 
INT PingAddress (HWND hWnd, LPTSTR IpszPingAddr, LPTSTR IpszOut) { 
HANDLE hPing; 
BYTE bOut[l32]; 
BYTE bIn[1024]; 
char cOptions[12]; 
char szdbAddr[32]; 
IP_OPTION_INFORMATION ipoi; 
PICMP_ECHO_REPLY pEr; 
struct in_addr Address; 
ONT 44.3% FC: 
DWORD adr; 


// Convert xXx.xx.xx.xx string to a DWORD. First, convert the string 
// to ascii. 
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wcstombs (szdbAddr, lpszPingAddr, 31); 
if ((adr = inet_addr(szdbAddr)) == -1L) 
return -1; 


// Open icmp handle. 

hPing = IcmpCreateFile (); 

if (hPing == INVALID_HANDLE_VALUE) 
return -2; 


wsprintf (IpszOut, TEXT ("Pinging: %s\n\n"), IlpszPingAddr) ; 
lpszOut += Istrlen (lpszOut) + 1; 


// Ping loop 
for (j = @; j < 5; j+) { 


// Initialize the send data buffer. 
memset (&bOut, @, sizeof (bOut)); 


// Initialize the IP structure. 

memset (&ipoi, @, sizeof (ipoi)); 
jpoi.Ttl = 32; 

ipoi.Tos Q; 

jpoi.Flags = IP_FLAG_DF; 

memset (cOptions, @, sizeof (cOptions)):; 


// Ping! 
rc = IcmpSendEcho (hPing, adr, bOut, sizeof (bOut), &ipoi, 
. bIn, sizeof (bIn), 1000); 
if (re) { 
// Loop through replies. 
pEr = (PICMP_ECHO_REPLY )bIn; 
for Gi = 02.7 < res - iF) 4 


Address.S_un.S_addr = (IPAddr)pEr->Address; 

// Format output string 

wsprintf (lpszOut, 
TEXT ("Reply from %hs: bytes:%d time"), 
jinet_ntoa (Address), pEr->DataSize); 


// Append round-trip time. 
if (pEr->RoundTripTime < 10) 
Tstrcat (lpszOut, TEXT ("<1@mS\n")); 
else 
wsprintf (&lpszOut[Istrlen(]lpszOut)], 
TEXT ("%dmS\n"), pEr->RoundTripTime) ; 


TpszOut += Istrien (lpszOut) + 1; 
pEPEF: 
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} 

} else { 
lstrcpy (lpszOut, TEXT ("Request timed out.")); 
TpszOut += Istrlen (lpszOut) + 1; 


j 
} 
IcmpCloseHandle (hPing); 
*]pszOut = TEXT ('\@'); // Add final terminating zero. 
return Q; 


The response packet from IcmpSendEcho is interpreted by looping through the 
array of ICMP_ECHO_REPLY structures. Within each of these structures is enough data 
to provide the very basic ping information. The routine could be extended in a num- 
ber of ways. For example, the reply packets could be dissected to determine the route 
of the packets. 

This chapter has given you a basic introduction to some of the networking fea- 
tures of Windows CE. Next on our plate is networking from a different angle. In 
Chapter 11, we look at the Windows CE device from the perspective of its compan- 
ion PC. The link between the Windows CE device and a PC is based on some of the 
same networking infrastructure that we touched upon here. Let’s take a look. 
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Connecting to 
the Desktop 


One of the major market segments that Windows CE is designed for is desktop com- 
panions. In answer to the requirements of this market, the first two product catego- 
ries created using Windows CE are desktop companions: the Handheld PC and the 
Palm-size PC. Both these products require a strong and highly functional link between 
the Windows CE device and the desktop PC running Windows 98 or Windows NT. 

Given this absolute necessity for good desktop connectivity, it’s not surprising 
that Windows CE has a vast array of functions that enable applications on the desk- 
top and the remote Windows CE device to communicate with one another. In gen- 
eral, most of this desktop-to-device processing takes place on the desktop. This is 
logical because the desktop PC has much greater processing power and more stor- 
age space than the less powerful and much smaller Windows CE system. 

The total of helper DLLs, communications support, and viewer programs is col- 
lected in a package named Windows CE Services. When a user buys any of the hori- 
zontal platforms, such as the Palm-size PC or the Handheld PC, a CD loaded with 
Windows CE Services comes with the device. The user becomes accustomed to seeing 
the Mobile Devices folder that, once Windows CE Services is installed, appears on his 
desktop. But there’s much more to Windows CE Services than Mobile Devices. A number 
of DLLs are included, for example, to help the Windows CE application developer write 
PC-based applications that can work with the remote Windows CE device. 

In this chapter, I’Il cover the various APIs that provide the desktop—to— 
Windows CE link. These include the Remote API, or RAPI, that allows applications 
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running on the desktop to directly invoke functions on the remote Windows CE sys- 
tem. I'll tell you how to write a file filter that converts files as they’re transferred from 
the PC to the Windows CE device and back. I'll also look at methods a PC applica- 
tion can use to notified itself when a connection exists between a PC and a Windows CE 
device. 

In a departure from the other chapters in this book, almost all the examples in 
this chapter are PC-based Windows programs. They’re written to work both for Win- 
dows 95/98 and Windows NT. I take the same approach with the PC-based examples as 
I do for the CE-based examples, writing to the API instead of using a class library such 
as MFC. The principles shown here could easily be used by MFC-based applications. 


THE WINDOWS CE REMOTE API 


The remote API (RAPD allows applications on one machine to call functions on an- 
other machine. Windows CE supports essentially a one-way RAPI; applications on 
the PC can call functions on a connected Windows CE system. In the language of 
RAPI, the Windows CE device is the RAPI server while the PC is the RAPI client. The 
application runs on the client, the PC, which in turn calls functions that are executed 
on the server, the Windows CE device. 


RAPI Overview 
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RAPI under Windows CE is designed so that PC applications can manage the Win- 
dows CE device remotely. The exported functions deal with the file system, registry, 
and databases, as well as functions for querying the system configuration. While most 
RAPI functions are duplicates of functions in the Windows CE API, a few functions 
extend the API. You use these functions mainly for initializing the RAPI subsystem 
and enhancing performance of the communication link by compressing iterative op- 
erations into one RAPI call. 

The RAPI functions are listed in the Windows CE API reference but are called by 
PC applications—not by Windows CE applications. The RAPI functions are prefixed 
with a Ce in the function name to differentiate them from their Windows CE-side coun- 
terparts; for example, the function GetStoreInformation in Windows CE is called 
CeGetStoreInformation in the RAPI version of the function. Unfortunately, some APIs 
in Windows CE, such as the database API, also have functions prefixed with Ce. In 
these cases, both the CE function (for example, CeCreateDatabase) and the RAPI func- 
tion (again, CeCreateDatabase) have the same name. The linker isn’t confused in this 
case because a Windows CE application won’t be calling the RAPI function and a PC 
based program can’t call the database function except through the RAPI interface. 

As I said, these Windows CE RAPI functions work for Windows 95/98 as well 
as Windows NT, but because they’re Win32 functions applications developed for the 
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Win16 API can’t use the Windows CE RAPI functions. The RAPI functions can be called 
from either a Windows-based application or a Win32-console application. All you have 
to do to use the RAPI functions is to include the RAPI.h header file and link with the 
RAPI.lib library. 

Essentially, RAPI is a remote procedure call. It communicates a PC application’s 
request to invoke a function and returns the results of that function. Because the RAPI 
layer is simple on the Windows CE side, all strings used in RAPI functions must be in 
Unicode regardless of whether the PC-based application calling the RAPI function 
uses the Unicode format. 


Dealing with different versions of RAPI 

The problem of versioning has always been an issue with redistributable DLLs under 
Windows. RAPI.DLL, the DLL on the PC that handles the RAPI API, is distributed with 
the Mobile Devices software that comes with an H/PC, Palm-size PC, or other PC 
companion Windows CE devices. Trouble arises because the RAPI API has been ex- 
tended over time as the Windows CE functions have expanded; you have to be aware 
that the RAPI DLL you load on a machine might not be the most up-to-date RAPI DLL. 
Older RAPI DLLs don’t have all the exported functions that the newest RAPI DLL has. 

For example, any RAPI DLL distributed with a device running Windows CE 2.1 
or later will export the newer database Ex functions so that you can manipulate da- 
tabases that aren’t in the object store of the remote device. However, if you assume 
that those functions are there and you run your RAPI application on a PC with an 
older RAPI DLL, the application won’t load because the extended database functions 
aren’t exported by the older DLL. 

On the other hand, just because you’re using the latest RAPI DLL doesn’t mean 
that the Windows CE system on the other end of the RAPI connection supports all 
the functions that the RAPI DLL supports. An H/PC running Windows CE 2.0 won’t 
support the extended database API of Windows CE 2.1 no matter what RAPI DLL you’re 
using on the PC. 

The best way to solve the problem of multiple versions of RAPI.DLL is to pro- 
gram defensively. Instead of loading the RAPI DLL implicitly by specifying an import 
library and directly calling the RAPI functions, you might want to load the RAPI DLL 
explicitly with a call to LoadLibrary. You can then access the exported functions by 
calling GetProcAddress for each function and then by calling the pointer to that function. 

The problem of different versions of Windows CE has a much easier solution. 
Just be sure to call CeGetVersionEx to query the version of Windows CE on the re- 
mote device. This gives you a good idea of what the device capabilities of that de- 
vice are. If the remote device has a newer version of Windows CE than RAPI.DLL, 
you might want to inform the user of the version issue and suggest an upgrade of the 
synchronization software on the PC. 


635 


Part Ill 


Initializing RAPI 

Before you can call any of the RAPI functions, you must first initialize the RAPI li- 
brary with a call to either CeRapilnit or CeRapilnitEx. The difference between the 
two functions is that CeRapiInit blocks, waiting on a successful connection with a 
Windows CE device, while CeRapilnitEx doesn’t block. Contrary to what you might 
expect, neither of these functions creates a connection between a PC and a device 
physically hooked up to one another but unconnected. 

The first initialization function is prototyped as 


HRESULT CeRapilInit (void); 


This function has no parameters. When the function is called, Windows looks for an 
established link to a Windows CE device. If one doesn’t exist, the function blocks 
until one is established or another thread in your application calls CeRapiUninit, which 
is generally called to clean up after a RAPI session. The return value is either 0, indi- 
cating that a RAPI session has been established, or the constant E_FAIL, indicating an 
error. In this case, you can call GetLastError to diagnose the problem. 

Unfortunately Cekapilnit blocks, sometimes, for an extended period of time. 
To avoid this, you can use the other initialization function, 


~ HRESULT CeRapiInitEx (RAPIINIT* pRapilnit); 
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The only parameter is a pointer to a RAPIINIT structure defined as 


typedef struct _RAPIINIT { 
DWORD cbSize; 
HANDLE heRapilinit; 
HANDLE hrRapilnit; 

} RAPIINIT; 


The cbSize field must be filled in before the call is made to CeRapilnitEx. After the 
size field has been initialized, you call CeRapilnitEx and the function returns without 
blocking. It fills in the second of the two fields, heRapiInit, with the handle to an 
event object that will be signaled when the RAPI connection is initialized. You can 
use WaitForSingleObject to have a thread block on this event to determine when the 
connection is finally established. When the event is signaled, the final field in the 
structure, brRapilnit, is filled with the return code from the initialization. This value 
can be 0 if the connection was successful or E_FAIL if the connection wasn’t made 
for some reason. 


Handling RAPI errors 

When you’re dealing with the extra RAPI layer between the caller and the execution 
of the function, a problem arises when an error occurs: did the error occur because 
the function failed or because of an error in the RAPI connection? RAPI functions return 
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error codes indicating success or failure of the function. If a function fails, you can 
use the following two functions to isolate the cause of the error: 


HRESULT CeRapiGetError (void); 
and 
DWORD CeGetLastError (void); 


The difference between these two functions is that CeRapiGetError returns an error 
code for failures due to the network or other RAPI-layer reasons. On the other hand, 
CeGetLastError is the RAPI counterpart to GetLastError, it returns the extended error for 
a failed function on the Windows CE device. So, if a function fails, call CeRapiGetError 
to determine whether an error occurred in the RAPI layer. If CeRapiGetError returns 
0, the error occurred in the original function on the CE device. In this case, a call to 
CeGetLastError returns the extended error for the failure on the device. 

Here’s one last general function, used to free buffers that are returned by some 
of the RAPI functions. This function is 


HRESULT CeRapiFreeBuffer (LPVOID Buffer); 


The only parameter is the pointer to the buffer you want to free. The function re- 
turns SOK when successful and E_FAIL if not. Throughout the explanation of RAPI 
functions, I’ll mention those places where you need to use CeRapiFreeBuffer. In gen- 
eral, though, you use this function anywhere a RAPI function returns a buffer that it 
allocated for you. 


Ending a RAPI session 
When you have finished making all the RAPI calls necessary, you should clean up 
by calling 


HRESULT CeRapiUninit (void); 


This function gracefully closes down the RAPI communication with the remote de- 
vice. CeRapiUninit returns E_FAIL if a RAPI session hasn’t been initialized. 


Predefined RAPI Functions 


As I mentioned in the beginning of this chapter, the RAPI services include a number of 
predefined RAPI functions that duplicate Windows CE functions on the PC side of the 
connection. So, for example, just as GetStoreInformation returns the size and free space 
of the object store to a Windows CE program, CeGetStoreInformation returns that same 
information about a connected Windows CE device to a PC-based application. The 
functions are divided into a number of groups that Ill talk about in the following pages. 
Since the actions of the functions are identical to their Windows CE-based counterparts, 
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I won’t go into the details of each function. Instead, although I'll list every RAPI func- 
tion, I'll explain at length only the functions that are unique to RAPI. 


RAPI system information functions 

The RAPI database functions are shown in the following list. I’ve previously described 
most of the counterpart Windows CE functions shown, with the exception of CeGet- 
Password and CeRapilnvoke. The CeGetPassword function, as well as its Windows CE 
counterpart GetPassword, compares a string to the current system password. If the 
strings match, the function returns TRUE. The comparison is case specific. Another 
function you might not recognize is CeGetDesktopDeviceCaps. This is the RAPI 
equivalent of GetDeviceCaps on the Windows CE side. 


System information functions 
CeGetVersionEx 
CeGlobalMemoryStatus 
CeGetSystemPowerStatusEx 
CeGetStoreInformation 
CeGetSystemMetrics 
CeGetDesktopDeviceCaps 
CeGetSystemInfo 
CeCheckPassword 


CeCreateProcess 


RAPI file and directory management functions 

The following list shows the RAPI file management functions, illustrating that almost 
any file function available to a Windows CE application is also available to a PC-based 
program. 


File and directory management functions 
CeFindAllFiles 
CeFindFirstFile 
CeFindNextFile 
CeFindClose 
CeGetFileAttributes 
CeSetFileAttributes 
CeCreateFile 
CeReadFile 
CeWriteFile 
CeCloseHandle 
CeSetFilePointer 
CeSetEndOfFile 
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CeCreateDirectory 
CeRemoveDirectory 
CeMoveFile 
CeCopyFile 
CeDeleteFile 
CeGetFileSize 
CeGetFileTime 
CeSetFileTime 


Here’s a new function, CeFindAllFiles, that’s not even available to a Windows 
CE application. This function is prototyped as 


BOOL CeFindAl|]Files (LPCWSTR szPath, DWORD dwFlags, 
LPDWORD IpdwFoundCount, 
LPLPCE_FIND_DATA ppFindDataArray) ; 


CeFindAllFiles is designed to enhance performance by returning all the files of a given 
directory with one call rather than having to make repeated RAPI calls using 
CeFindFirstFile and CeFindNextFile. The first parameter is the search string. This string 
must be specified in Unicode, so if you’re not creating a Unicode application, the TEXT 
macro won’t work because the TEXT macro produces char strings for non-Unicode 
applications. In Microsoft Visual C++, prefixing the string with an LZ before the quoted 
string as in Z”\\*.*” produces a proper Unicode for the function even in a non-Unicode 
application. For string conversion, you can use the WideCharToMultiByte and MultiByte- 
ToWideChar library functions to convert Unicode and ANSI strings into one another. 

The second parameter of the CeFindAllFiles function, dwFlags, defines the scope 
of the search and what data is returned. The first set of flags can be one or more of 
the following: 


M £FAF_ATTRIB_CHILDREN Return only directories that have child items. 
M FAF_ATTRIB_NO_HIDDEN Don’t report hidden files or directories. 
M FAF_FOLDERS_ONLY Return only folders in the directory. 
M FAF_NO_HIDDEN_SYS_ROMMODULES Don’t report ROM-based system 
files. 
The second set of flags defines what data is returned by the CeFindAIlFiles func- 
tion. These flags can be one or more of the following: 
M FAF_ATTRIBUTES Return file attributes. 
M FAF_CREATION_TIME Return file creation time. 
M FAF_LASTACCESS_TIME Return file last access time. 
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FAF_LASTWRITE_TIME Return file last write time. 
FAF_SIZE_HIGH Return upper 32 bits of file size. 
FAF_SIZE_ LOW Return lower 32 bits of file size. 
FAF_OID Return the OID for the file. 

FAF_NAME Return the filename. 


Just because the flags are listed above doesn’t mean you can find a good use 
for them. For example, the FAF_SIZE_HIGH flag is overkill, considering that few files 
on a Windows CE device are going to be larger than 4 GB. The file time flags are also 
limited by the support of the underlying file system. For example, the Windows CE 
object store tracks only the last access time and reports it in all file time fields. 

There also appears to be a bug with the FAF_ATTRIB_CHILDREN flag. This 
valuable flag allows you to know when a directory contains subdirectories without 
your having to make an explicit call to that directory to find out. The flag seems to 
work only if the filename specification—the string to the right of the last directory 
separator backslash (\)—contains only one character. For example, the file specification 


\\windows \* 
works with FAF_ATTRIB CHILDREN, while 
\\windows\#*.* 


returns the same file list but the flag FILE_LATTRIBUTE_HAS_CHILDREN isn’t set for 
directories that have subdirectories. 

The third parameter of CeFindAllFiles should point toa DWORD value that will 
receive the number of files and directories found by the call. The final parameter, 
DpFindDataArray, should point to a variable of type LPCE_FIND_DATA, which is a 
pointer to an array of CE_FIND_DATA structures. When CeFindAllFiles returns, this 
variable will point to an array of CE_FIND_DATA structures that contain the requested 
data for each of the files found by the function. The CE_FIND_DATA structure is 
defined as 


typedef struct _CE_FIND_DATA { 
DWORD dwFileAttributes; 
FILETIME ftCreationTime; 
FILETIME ftLastAccessTime; 
FILETIME ftLastWriteTime; 
DWORD nFileSizeHigh; 
DWORD nFileSizeLow; 
DWORD dwOID; 
WCHAR cFileName[MAX_PATH]; 
} CE_FIND_DATA; 
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The fields of CE_FIND_DATA look familiar to us by now. The only interesting 
field is the dwOID field that allows a PC-based application to receive the OID of a 
Windows CE file. This can be used with CeGetOidGetInfo to query more information 
about the file or directory. The flags in the dwFileAttributes field relate to Windows CE 
file attributes even though your application is running on a PC. This means, for ex- 
ample, that the FILE_ATTRIBUTE_TEMPORARY flag indicates an external storage 
device like a PC Card. Also, attribute flags are defined for execute in place ROM files. 
The additional attribute flag, FILE_ATTRIBUTE_HAS_CHILDREN, is defined to indi- 
cate that the directory contains child directories. 

The buffer returned by CeFindAllFiles is originally allocated by the RAPI.DLL. Once 
you have finished with the buffer, you must call CeRapiFreeBuffer to free the buffer. 


RAPI database functions 

The RAPI database functions are shown in the following list. As you can see, these 
functions mimic the extensive database API found in Windows CE. Here’s a case in 
which explicitly loading the RAPI DLL can come in handy. The many RAPI functions 
that support the extended database API of Windows CE 2.1 aren’t exported by older 
RAPI DLLs. If your application attempts implicitly to load one of these functions, it 
won't load if the PC has an older version of RAPI.DLL. 


Database management functions Support in 
CeCreateDatabase 

CeCreateDatabaseEx Windows CE 2.1 or later 
CeDeleteDatabase 

CeDeleteDatabaseEx Windows CE 2.1 or later 
CeDeleteRecord 

CeFindFirstDatabase 

CeFindFirstDatabaseEx Windows CE 2.1 or later 
CeFindNextDatabase 

CeFindNextDatabaseEx Windows CE 2.1 or later 
CeOidGetInfo 

CeOidGetInfoEx Windows CE 2.1 or later 
CeOpenDatabase 

CeOpenDatabaseEx Windows CE 2.1 or later 
CeReadRecordProps 

CeReadRecordPropsEx Windows CE 2.1 or later 
CeSeekDatabase 

CeSetDatabaselnfo 

CeSetDatabaseInfoEx Windows CE 2.1 or later 
CeWritekecordProps 


(continued) 
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continued 
Database management functions Support in 
CeMountDBVol Windows CE 2.1 or later 
CeUnmountDBVol Windows CE 2.1 or later 
CeEnumDBVolumes Windows CE 2.1 or later 
CeFindAllDatabases | 


All but one of the database functions has a Windows CE counterpart. The only 
new function is CeFindAllDatabases. Like CeFindAllFiles, this function is designed 
as a performance enhancement so that applications can query all the databases on 
the system without having to iterate using the FindFirstDatabase and FindNext- 
Database functions. The function is prototyped as 


BOOL CeFindAl1]1Databases (DWORD dwDbaseType, WORD wFlags, 
LPWORD cFindData, 
LPLPCEDB_FIND_DATA ppFindData) ; 


The first parameter is the database type value, or 0, if you want to return all 
databases. The wFlags parameter can contain one or more of the following flags, which 
define what data is returned by the function. 


FAD_OID Returns the database OID 

FAD_FLAGS Returns the dwFlags field of the DbInfo structure 
FAD_NAME_ Returns the name of the database 

FAD_TYPE Returns the type of the database 

FAD_NUM_RECORDS Returns the number of records in the database 
FAD_NUM_SORT_ORDER Returns the number of sort orders 
FAD_SORT_SPECS Returns the sort order specs for the database 


The cFindData parameter should point to a WORD variable that receives the 
number of databases found. The last parameter should be the address of a pointer 
to an array of CEDB_FIND_DATA structures. As with the CeFindAllFiles function, 
CeFindAllDatabases returns the information about the databases found in an array 
and sets the ppFindData parameter to point to this array. The CEDB_FIND_DATA 
structure is defined as 


struct CEDB_FIND_DATA { 
CEOID OidDb; 
CEDBASEINFO DbInfo; 
+5 


The structure contains the OID for a database followed by a CEDBASEINFO 
structure. I described this structure in Chapter 7, but I’ll repeat it here so that you can 
see what information can be queried by FindAllDatabases. 
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typedef struct _CEDBASEINFO { 

DWORD dwFlags; 

WCHAR szDbaseName[CEDB_MAXDBASENAMELEN]; 

DWORD dwDbaseType; 

WORD wNumRecords; 

WORD wNumSortOrder; 

DWORD dwSize; 

FILETIME ftLastModi fied; 

SORTORDERSPEC rgSortSpecs[CEDB_MAXSORTORDER]; 
} CEDBASEINFO; 


As with CeFindAllFiles, you must free the buffer returned by CeFindAllDatabases with 
a call to CeRapiFreeBuffer. 

One other function in this section requires a call to CeRapiFreeBuffer. The func- 
tion CeReadRecordProps, which returns properties for a database record, allocates 
the buffer where the data is returned. If you call the RAPI version function, you need 
to call CeRapiFreeBuffer to free the returned buffer. 


RAPI registry management functions 

The RAPI functions for managing the registry are shown in the following list. The 
functions work identically to their Windows CE counterparts. But remember that all 
strings, whether they are specifying keys and values or strings returned by the func- 
tions, are in Unicode. 


Registry management functions 
CeRegOpenKeyEXx 
CeRegEnumKeyEx 
CekegCreateKeyEx 
CeRegCloseKey » 
CeRegDeleteKey 
CeRegEnum Value 
CekegDelete Value 
CeRegQuerylnfoKey 
CekegQueryValueEx 
CekegSetValueEx 


RAPI shell management functions 

The RAPI shell management functions are shown in the first list on the following page. 
While TPIl cover the Windows CE-equivalent functions in the next chapter, you can 
see that the self-describing names of the functions pretty well document themselves. 
The CeSHCreateShortcut and CeSHGetShortcutTarget functions allow you to create 
and query shortcuts. The other two functions, CeGetTempPath and CeGetSpecial- 
FolderPath, \et you query the locations of some of the special-purpose directories on 
the Windows CE system, such as the programs directory and the recycle bin. 
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Shell management functions 
CeSHCreateShoricut 
CeSHGetShortcutTarget 
CeGetTempPath 
CeGetSpecialFolderPath 


RAPI window management functions 

The final set of predefined RAPI functions allow a desktop application to manage the 
windows on the Windows CE desktop. These functions are shown in the following list. 
The functions work similarly to their Windows CE functions. The CeGetWindow func- 
tion allows a PC-based program to query the windows and child windows on the desk- 
top while the other functions allow you to query the values in the window structures. 


Window management functions 
CeGetWindow 

CeGetWindowLong 

CeGet WindowText 
CeGetClassName 


The RapiDir Example Program 
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The RapiDir example is a PC-console application that displays the contents of 
a directory on an attached Windows CE device. The output of RapiDir, shown in 
Figure 11-1, resembles the output of the standard DIR command from a PC command 
line. RapiDir is passed one argument, the directory specification of the directory on 
the Windows CE machine. The directory specification can take wildcard arguments 
such as “exe if you want, but the program isn’t completely robust in parsing the di- 
rectory specification. Perfect parsing of a directory string isn’t the goal of RapiDir— 
demonstrating RAPI is. 


\cebook\11. Connecting to the Desktop\RAPIDIR\DEBUG>rapidir \ 


<DIR> Storage Card 
prowicechi0.doc 
<DIR> Temporary Internet Files 
<DIR> Recycled 
<DIR> Program Files 
<DIR> My Documents 
<DIR> Temp 
<DIR> Windows 
93032 bytes 


ebook\11. Connecting to the Desktop\RAPIDIR\DEBUG> 


Figure 11-1. 7e output of RapiDir. 
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The source code for RapiDir is shown in Figure 11-2. The program is a com- 
mand line application and therefore doesn’t need the message loop or any of the other 
structure seen in a Windows-based application. Instead the WinMain function is re- 
placed by our old C friend, main. 

Remember that RapiDir is a standard Win32 desktop application. It won’t even 
compile for Windows CE. On the other hand, you have the freedom to use the copi- 
ous amounts of RAM and disk space provided by the comparatively huge desktop 
PC. When you build RapiDir, you’ll need to add rapi.lib to the libraries that the linker 
uses. Otherwise, you’ll get unresolved external errors for all the RAPI functions you 
call in your application. 


Figure 11-2. The RapiDir source code. (continued) 
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This single procedure application first calls CeRapilnitEx to initialize the RAPI 
session. I used the Ex version of the initialization function so that RapiDir can time 
out and terminate if a connection isn’t made within 5 seconds of starting the program. 
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If I'd used CeRapilnit instead, the only way to terminate RapiDir if a remote CE de- 
vice weren’t connected would be a user-unfriendly Control-C key combination. 

Once the RAPI session is initialized, a minimal amount of work is done on the 
single command line argument that’s the search string for the directory. Once that 
work is complete, the string is converted into Unicode and passed to CeFindAllFiles. 
This RAPI function then returns with an array of CE_FIND_DATA structures that con- 
tain the names and requested data of the files and directories found. The data from 
that array is then displayed using printf statements. Finally, the RAPI session is termi- 
nated with a call to CeRapiUninit. 

If you compare the output of RapiDir with the output of the standard DIR com- 
mand, you notice that RapiDir doesn’t display the total bytes free on the disk after 
the listing of files. While I could have displayed the total free space for the object 
store using CeGetStorageInformation, this wouldn’t work if the user displayed a di- 
rectory on a PCMCIA card or other external media. Windows CE supports the 
GetDiskFreeSpaceEx function, but the Windows CE RAPI DLL doesn’t expose this 
function. To get this information, we’ll use RAPI’s ability to call user defined func- 
tions on a Windows CE system. 


Custom RAPI Functions 
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No matter how many functions the RAPI interface supports, you can always think of 
functions that an application needs but the RAPI interface doesn’t give you. Because 
of this, RAPI provides a method for a PC application to call a user-defined function 
on the Windows CE device. 

You can invoke a user-defined RAPI function in one of two ways. The first way 
is called block mode. In block mode, you make a call to the RAPI remote invocation 
function, the function makes the call to a specified function in a specified DLL, the 
DLL function does its thing and returns, and the RAPI function then returns to the 
calling PC program with the output. The second method is called stream mode. In 
this mode, the RAPI call to the function returns immediately, but a connection is 
maintained between the calling PC application and the Windows CE DLL—-based func- 
tion. This method allows information to be fed back to the PC on an ongoing basis. 


Using RAPI to call a custom function 
The RAPI function that lets you call a generic function on the Windows CE device is 
CekapiInvoke, which is prototyped as 


HRESULT CeRapilInvoke (LPCWSTR pDI1Path, LPCWSTR pFunctionName, 
DWORD cbInput, BYTE *pInput, DWORD *pcbOutput, 
BYTE **ppOutput, IRAPIStream **ppIRAPIStream, 
DWORD dwReserved) ; 
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The first parameter to CeRapilnvoke is the name of the DLL on the Windows CE 
device that contains the function you want to call. The name must be in Unicode but 
can include a path. If no path is specified, the DLL is assumed to be in the \windows 
directory on the device. The second parameter is the name of the function to be called. 
The function name must be in Unicode and is case specific. 

The next two parameters, cbInput and plnput, should be set to the buffer con- 
taining the data and the size of that data to be sent to the Windows CE-based func- 
tion. The pcebOutput and ppOutput parameters are both pointers—the first a pointer 
to a DWORD that receives the size of the data returned and the second a pointer to a 
PBYTE variable that receives the pointer to the buffer containing the data returned by 
the Windows CE function. I'll describe the next-to-last parameter, pp/RAPIStream, later. 

To use CeRapilnvoke in block mode, all you do is specify the DLL containing 
the function you want to call, the name of the function, and the data and make the 
call. When CeRapilnvoke returns, the data from the CE-based function will be sitting 
in the buffer pointed to by your output pointer variable. 


Writing a RAPI server function 
You can’t just call any function in a Windows CE DLL. The structure of the Windows CE 
function must conform to the following function prototype: 


STDAPI INT FuncName (DWORD cbInput, BYTE *pInput, DWORD *pcbOutput, 
BYTE **ppOutput, IRAPIStream *pIRAPIStream) ; 


As you can see, the parameters closely match those of CeRapilnvoke. As with 
CeRapilnvoke, I'll talk about the parameter plRAPIStream, later. 

Figure 11-3 contains the source code for a very simple block-mode RAPI server. 
This is a DLL and therefore has a different structure from the application files previ- 
ously used in the book. The primary difference is that the DLL contains a LibMain 
routine instead of WinMain. The LibMain routine is called by Windows whenever a 
DLL is loaded or freed by a process or thread. In our case, we don’t need to take any 
action other that to return TRUE indicating all is well. 

You should be careful to make the name of your RAPI server DLL eight charac- 
ters or less. Current implementations of the RAPI DLL will fail to find server DLLs with 
names not in the old 8.3 format. 


Figure 11-3. RapiServ.c, a simple block-mode RAPI server DIL. (continued) 
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The unusual prefix before the function prototype for RAP/GetDiskSize, 


__declspec (dllexport) INT RAPIGetDiskSize... 


tells the linker to export the function listed so that external modules can call the func- 
tion directly. This declaration is a shortcut for the old way of defining exports in a 
separate function definition (DEF) file used in Win16 programming. While this short- 
cut is convenient, sometimes you still need to fall back on a DEF file. 

The function of RapiServ is to make available that GetDiskFreeSpaceEx function 
we needed in the RapiDir example application. The server function, RAPIGetDiskSize, 
has the same prototype I described earlier. The input buffer is used to pass a direc- 
tory name to the DLL while the output buffer returns the total disk space and the free 
disk space for the directory passed. The format of the input and output buffers is totally 
up to you. However, the output buffer should be allocated using LocalAlloc so that the 
RAPI library can free it after it has been used. The value returned by RAPIGetDiskSize 
is the value that’s returned by the Cekapilnvoke function to the PC-based application. 

On the PC side, a call to a block mode RAPI server function looks like the 
following. 


// MyCeGetDiskFreeSpaceEx - Homegrown implementation of a RAPI 
// GetDiskFreeSpace function 
// 
BOOL MyCeGetDiskFreeSpaceEx (LPWSTR pszDir, PDWORD pdwTotal, 
PDWORD pdwFree) { 
HRESULT hr; 
DWORD dwIn, dwOQut; 
LPBYTE pInput; 
LPWSTR pPtr; 
PDWORD pOut; 


// Get length of Unicode string. 
for (dwiIn = 2, pPtr = pszDir; *pPtr++; dwInt=2); 
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// Allocate buffer for input. 
pInput = LocalAlloc (LPTR, dwIn); 
if (!pInput) 
return FALSE; 
// Copy directory name into input buffer. 
memcpy (pInput, pszDir, dwin); 


// Call function on Windows CE device. 3 
hr = CeRapiInvoke (L"\\RapiServ", L"RAPIGetDiskSize", dwIn, 
pInput, &dwOut, (PBYTE *)&pOut, NULL, @); 


// If successful, return total and free values. 
if (hr == 0) { 

*pdwlotal = pOut[Q]; 

*«pdwFree = pOut[1]; 

CeRapiFreeBuffer (pOut); 

return TRUE; 


} 
return FALSE; 


This routine encapsulates the call to CeRapiInvoke so that the call looks just like 
another CE RAPI call. The code in this routine simply computes the length of the 
Unicode string that contains the directory specification, allocates a buffer and copies 
the string into it, and passes it to the CeRapilnvoke function. When the routine re- 
turns, the return code indicates success or failure of the call. CeRapiInvoke frees the 
input buffer passed to it. The data is then copied from the output buffer and that buffer 
is freed with a call to CekapiFreeBuffer. 

Throughout this section, ’ve put off any explanation of the parameters refer- 
ring to IRAPISiream. In fact, in the example code above, the prototype for the server 
call, RAPIGetDiskSize, simply typed the plRAPIStream pointer as a PVOID and ignored 
it. In the client code, the CeRapilnvoke call passed a NULL to the ppIRAPIStream 
pointer. This treatment of the JRAPIStream interface is what differentiates a block- 
mode call from a stream-mode call. Now let’s look at the JRAPIStream interface. 


Stream mode 

Stream-mode RAPI calls are different from block mode in that the initial RAPI call 
creates a link between the PC application and the server routine on the Windows CE 
device. When you call CeRapilnvoke in stream mode, the call returns immediately. 
You communicate with the server DLL using an JRAPIStream interface. You access 
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this interface using a pointer returned by the CeRapilnvoke call in the variable pointed 
to by ppIRAPIStream. 

The IRAPIStream interface is derived from the standard COM IJStream interface. 
The only methods added to JStream to create IRAPIStream are SetRapiStat and 
GetRapiStat, which let you set a timeout value for the RAPI communication. Fortu- 
nately, we don’t have to implement an JRAPIStream interface either on the client side 
or in the server DLL. This interface is provided for us by the RAPI services as a way to 
communicate. 

Following is a call to CeRapilnvoke that establishes a stream connection and 
then writes and reads back 10 bytes from the remote server DLL. 


DWORD dwIn, dwOut, cbBytes; 
IRAPIStream *pIRAPIStream; 
BYTE bBuff[BUFF_SIZE]; 
PBYTE pOut; 

HRESULT hr; 


// RAPI call 

hr = CeRapilInvoke (L"ServDLL", L"RAPIRmtFunc", dwin, bBuff, 

7 &dwOut, &pOut, &pIRAPIStream, Q); 

if (hr == S_OK) { 
// Write 1@ bytes. 
pIRAPIStream->Write (bBuff, 10, &cbBytes); 
// Read data from server. 
pIRAPIStream->Read (bBuff, 10, &cbBytes); 


When establishing a stream connection, you can still use the input buffer to pass 
initial data down to the remote server. From then on, you should use the Read and 
Write methods of IRAPIStream to communicate with the server. 


The RapiFind Example Program 


The RapiFind example program searches the entire directory tree of a Windows CE 
device for files matching a search specification. The program is in two parts: a RAPI 
server DLL, FindSrv.DLL, and a console-based, Win32 application, RapiFind. The 
program works by passing a search string on the command line. RapiFind returns 
any files on the attached Windows CE device that match the search string. If the search 
specification includes a directory, only that directory and any of its subdirectories are 
searched for matching files. Figure 11-4 on the following page shows the output of 
RapiFind. 
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Figure 11-4. 7he output of RapiFind. 


You'll notice that the following example is written in C++, and so are the rest of 
the examples in this chapter. Actually, almost all the code in both files is standard C, 
but the C++ extensions are used to reference the JRAPIStream interface. I could have 
written a C-equivalent structure to access the interface, but I could see little reason to 
avoid using C++ in this case. (As an aside, most COM interfaces defined in Win32 
have C-interface equivalents for those of us who still like C.) First, let’s look at the 
server DLL, FindSrv, shown in Figure 11-5. 


Figure 11-5. FindSrv.cpp, a stream-mode RAPI server DLL. 
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Figure 11-5. continued 
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Figure 11-5. continued 
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all subdirectories underneath. When a file is found that matches the search specifica- 
tion, the name and size of the file is sent back to the client caller using the Write method 
of IRAPIStream. The format of the data transmitted between the client and server is 
up to the programmer. In this case, I send a command word, followed by the file 
size, the length of the name, and finally the filename itself. The command word gives 
you a minimal protocol for communication with the client. A command value of 1 
indicates a found file, a value of 2 indicates the server is looking in a new directory, 
and a value of 0 indicates that the search is complete. 

The source code for the client application, RapiFind, is shown in Figure 11-6. 


Figure 11-6. RapiFind.cpp, a stream-mode RAPI client application. (continued) 
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Figure 11-6. continued 


The call to CeRapilnvoke returns a pointer to an JRAPIStream interface that’s then 
used to read data from the server. The client reads one integer value to determine whether 
the following data is a found file, a report of the current search directory, or a report 
that the search has ended. With each command, the appropriate data is read using the 
Read method. The result of the search is then reported using printf statements. 

While you could implement the same file find function of RapiFind using a block- 
mode connection, the stream format has a definite advantage in this case. By report- 
ing back results as files are found, the program lets the user known that the program 
is executing correctly. If the program were designed to use a block-mode call, RapiFind 
would appear to go dead while the server DLL completed its entire search, which 
could take 10 or 20 seconds. 

As I mentioned in the explanation of CeRapilnit, a call to this function doesn’t initiate 
a connection to a device. You can, however, be notified when a connection to a Win- 
dows CE device is established. There are ways, both on the PC and on the Windows CE 
device, to know when a connection is made between the two systems. After a brief look 
at CeUtil, which provides some handy helper functions for PC applications dealing with 
Windows CE devices, Ill talk about connection notifiers in the next section. 


THE CEUTIL FUNCTIONS 
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Windows CE Services uses the PC registry to store voluminous amounts of informa- 
tion about the Windows CE devices that have partnered with the PC. Windows CE 
Services also uses the registry to store extensive configuration information. While most 
of these registry keys are documented, if you access them by name you’re assuming 
that those key names will always remain the same. This might not be the case, espe- 
cially in international versions of Windows where registry keys are sometimes in a 
different language. 
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The CeUtil DLL exports functions that provide an abstraction layer over the 
registry keys used by Windows CE Services. Using this DLL allows a PC application 
to query the devices that are currently registered and to add or delete registry values 
underneath the keys that hold data for specific devices. The CeUtil DLL doesn’t com- 
municate with a remote Windows CE device; it only looks in the PC registry for infor- 
mation that has already been put there by Windows CE Services. 

The keys in the registry related to Windows CE Services are separated into either 
HKEY_LOCAL_MACHINE, for generic configurations such as the initial configuration 
for a newly registered device, or HKEY_CURRENT_USER, where the configuration 
information for the already registered devices is located. When a new device is reg- 
istered, CE Services copies the template in HKEY_LOCAL_MACHINE to a new subkey 
under HKEY_CURRENT_USER that identifies the specific device. 

In general, you register a new filter in the keys under HKEY_LOCAL_MACHINE 
to ensure that all devices that are registered in the future also use your filter. You use 
the registry entries under HKEY_CURRENT_USER to register that filter for a specific 
_ device that was already registered before you installed that same filter. 


Accessing Windows CE Services registry entries 
To open one of the many registry keys that hold connection information, you can 
use this function: 


HRESULT CeSvcOpen (UINT uSvc, LPTSTR pszPath, BOOL fCreate, 
PHCESVC phSvc); 


The first parameter of this function is a flag that indicates which predefined key you 
want to open. The available flags are listed below. 


Keys under HKEY_LOCAL MACHINE that apply to generic Windows CE 
Services configuration information 


M = CESVC_ROOT_MACHINE Windows CE Services root key under HKEY_ 
LOCAL_MACHINE 


CESVC_FILTERS Root key for filter registration 

CESVC_CUSTOM_MENUS Root key for custom menu registration 
CESVC_SERVICES_COMMON_ Root key for services 
CESVC_SYNC_COMMON Root key for synchronization services registration _ 


Keys under HKEY CURRENT_USER that apply to specific Windows CE 
devices that are partnered with the PC 


M CESVC_ROOT_USER Windows CE Services root key under HKEY_LOCAL_ 
USER 


M CESVC_DEVICES Root key for individual device registration 
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M CESVC_DEVICEX Root key for a specific device 


M CESVC_DEVICE_SELECTED Root key for the device currently selected in 
the Windows CE Services window 


M CESVC_SERVICES_USER Root services subkey for a specific device 
M CESVC_SYNC Synchronization subkey for a specific device 


Of the many registry keys that can be returned by CeSucOpen, the ones I'll be 
using throughout the chapter are CESVC_FILTERS, the key in which a filter is regis- 
tered for all future devices, CESVC_DEVICES, the key in which information for all reg- 
istered devices is located; and CESVC_DEVICEX, which is used to open keys for a specific 
registered devices. The other flags are useful for registering synchronization objects as 
well as for registering general Windows CE Services configuration information. 

The second parameter to CeSucOpen is pszPath. This parameter points either 
to the name of a subkey to open underneath the key specified by the uSuc flag or to 
a DWORD value that specifies the registered Windows CE device that you want to 
open if the uSuc flag requires that a device be specified. The fCreate parameter should 
be set to TRUE if you want to create the key being opened because it currently doesn’t 
exist. If this parameter is set to FALSE, CeSvcOpen fails if the key doesn’t already exist 
in the registry. Finally, the pbSvc parameter points to a CESVC handle that receives 
the handle of the newly opened key. While this isn’t typed as a handle to a registry 
key (an HKEY), the key can be used in both the CeUtil registry functions as well as 
the standard registry functions. 

CeSucOpen returns a standard Win32 error code if the function fails. Otherwise, 
the key to the opened registry key is placed in the variable pointed to by phSuc. 

You can open registry keys below those opened by CeSvcOpen by calling 
CeSucOpenEx. This function is prototyped as 


HRESULT CeSvcOpenEx (HCESVC hSvcRoot, LPTSTR pszPath, BOOL fCreate, 
PHCESVC phSvc); 


The parameters for this closely mirror those of RegOpenKey. The first parame- 
ter is a handle to a previously opened key. Typically, this key would have been opened 
by CeSucOpen. The second parameter is the string that specifies the name of the subkey 
to be opened. Notice that since we’re running on the PC, this string might not be a 
Unicode value. The fCreate parameter should be set to TRUE if you want the key to 
be created if it doesn’t already exist. Finally, the pbSvc parameter points to a CESVC 
handle that receives the handle to the opened key. 

When you have finished with a key, you should close it with a call to this function: 


HRESULT CeSvcClose (HCESVC hSvc); 


The only parameter is the handle you want to close. 
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Enumerating registered devices 

Of course, the requirement to specify the device ID value in CeSucOpen begs the 
question of how you determine what devices have already been partnered with the 
PC. To determine this, you can use the function 


HRESULT CeSvcEnumProfiles (PHCESVC phSvc, DWORD 1ProfileIndex, 
PDWORD p1Profile); 


The first parameter to CeSucEnumProfiles is a pointer to a CESVC handle. The 
handle this parameter points to is uninitiated the first time the function is called. 
The function returns a handle that must be passed in subsequent calls to CeSuc- 
EnumProfiles. The second parameter is an index value. This value should be set to 0 
the first time the function is called and incremented for each subsequent call. The 
final parameter is a pointer to a DWORD that receives the device ID for the regis- 
tered device. This value can be used when calling CeSucOpen to open a registry key 
for that device. 

Each time the function is called, it returns NOERROR if a new device ID is re- 
turned. When all devices have been enumerated, CeSucEnumProfiles returns ERROR_ 
NO_MORE_ITEMS. You should be careful to continue calling CeSucEnumProfiles until 
the function returns ERROR_NO_MORE_ITEMS so that the enumeration process will 
close the handle parameter pointed to by phSuc. If you want to stop enumerating after 
you've found a particular device ID, you'll need to call CeSucClose to close the bSuc 
handle manually. 

The following routine enumerates the Windows CE devices that have been reg- 
istered on the PC. The program enumerates all the registered Windows CE devices 
and prints out the name and device type of each of the devices. The program uses 
the function CeSucGetString, which ll describe shortly. 


int PrintCeDevices (void) { 
HCESVC hSvc, hDevKey; 
TCHAR szName[128], szType[64]; 
DWORD dwPro; 
INT 7; 


// Enumerate each registered device. 
i = Q; 
while (CeSvcEnumProfiles (&hSvc, i++, &dwPro) == @) { 


// Open the registry key for the device enumerated. 
CeSvcOpen (CESVC_DEVICEX, (LPTSTR)dwPro, FALSE, &hDevKey); 


// Get the name and device type strings. 
CeSvcGetString (hDevKey, TEXT ("DisplayName"), 
szName, dim(szName)); 
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CeSvcGetString (hDevKey, TEXT ("DeviceType"), 
szlype, dim(szType)); 


// Print to the console. 
printf (TEXT ("Name: %s\t\tType: %s"), szName, szType); 


// Close the key opened by CeSvcOpen. 
CeSvcClose (hDevKey); 


} 
return i-1; // Return the number of devices found. 


Reading and writing values 

The remainder of the CeUtil library functions concern reading and writing values in 
the registry. In fact, you can skip these functions and use the registry functions di- 
rectly, but the CeSvcxxx functions are a bit simpler to use. These functions allow you 
to read and write three of the data types used in the registry, DWORD, string, and 
binary data. These just happen to be the only data types used in the values under the 
Windows CE Services keys. The functions are all listed here: 


HRESULT CeSvcGetDword (HCESVC hSvc, LPCTSTR pszValName, 
LPDWORD pdwVal); 

HRESULT CeSvcSetDword (HCESVC hSvc, LPCTSTR pszValName, 
DWORD dwVal); 


HRESULT CeSvcGetString (HCESVC hSvc, LPCTSTR pszValName, 
LPTSTR pszVal, DWORD cbVal); 


HRESULT CeSvcSetString (HCESVC hSvc, LPCTSTR pszValName, 
LPCTSTR pszVal); 


HRESULT CeSvcGetBinary (HCESVC hSvc, LPCTSTR pszValName, 
LPBYTE pszVal, LPDWORD pcbVal); 


HRESULT CeSvcSetBinary (HCESVC hSvc, LPCTSTR pszValName, 
LPBYTE pszVal, DWORD cbVal); 


The parameters for these functions are fairly self-explanatory. The first parame- 
ter is the handle to an open key. The second parameter is the name of the value being 
read or written. The third parameter specifies the data or a pointer to where the data 
will be written. The fourth parameter on some of the functions specifies the size of 
the buffer for the data being read or, in the case of CeSucSetBinary, the length of the 
data being written. 

One final function in the CeUtil library is 


HRESULT CeSvcDeleteVal (HCESVC hSvc, LPCTSTR pszValName) ; 
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This function, as you might expect, lets you delete a value from the registry. The 
parameters are the handle to an open key and the name of the value to be deleted. 

The CeUtil library doesn’t provide any function that you couldn’t do yourself 
with a bit of work and the standard registry functions. However, using these func- 
tions frees you from having to depend on hard-coded registry key names that could 
change in the future. I strongly advise using these functions whenever possible when 
you're accessing registry entries that deal with Windows CE Services. 


CONNECTION NOTIFICATION 


Windows CE Services gives you two ways of notifying PC-based applications when a 
connection is made with a Windows CE device. The first method is to simply launch 
all the applications listed under a given registry key. When the connection is broken, 
all applications listed under another key are launched. This method has the advan- 
tage of simplicity at the cost of having the application not know why it was launched. 

The second method of notification is a COM-interface method. This notifica- 
tion method involves two interfaces: I[DccMan, provided by RAPI.DLL, and IDcc- 
ManSink, which must be implemented by the application that wants to be notified. 
This method has the advantage of providing much more information to the applica- 
tion as to what is actually happening at the cost of having to implement a COM-style 
interface. 


Registry Method 


To have your PC application launched when a connection is made to a Windows CE 
device, simply add a value to the PC registry under the following key: 


[HKEY_LOCAL_MACHINE] 
\Software\Microsoft\Windows CE Services\AutoStartOnConnect 


I'll show you shortly how to access this key using CeSucOpen so that the pre- 
cise name of the key can be abstracted. The name of the value under AutoStart- 
OnConnect can be anything, but it must be something unique. The best way to ensure 
this is to include your company name and product name plus its version in the value 
name. The actual data for the value should be a string that contains the fully speci- 
fied path for the application you want to launch. The string can only be the filename; 
appending a command line string causes an error when the program is launched. For 
example, to launch a myapp program that’s loaded in the directory c:\windowsce\ 
tools\syncstuff, the value and data might be 


MyCorpThisApp c:\windowsce\tools\syncstuff\myapp.exe 
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To have a command line passed to your application, you can have the entry in 
the registery point to a shortcut that will launch your application. The entry in the 
registry can’t pass a command line, but shortcuts don’t have that limitation. 

You can have an application launched when the connection is broken between 
the PC and the Windows CE device by placing a value under the following key: 


[HKEY_LOCAL_MACHINE] | 
\Software\Microsoft\Windows CE Services\AutoStart0OnDisconnect 


The format for the value name and the data is the same as the format used in the 
AutoStartOnConnect key. 

A routine to set these values is simple to write. The example routine below uses 
the CeSvucOpen and CeSucSetString functions to write the name of the module to the 
registry. Remember that since this routine runs on a PC, and therefore perhaps under 
Windows NT, you'll need administrator access for this routine to have write access to 
the registry. 


// 
// RegStartOnConnect - Have module started when connect occurs. 
// 
LPARAM RegStartOnConnect (HINSTANCE hInst) { 
TCHAR szName[MAX_PATH]; 
HCESVC hSve; 
HRESULT rc; 


// Get the name of the module. 
GetModuleFileName (hInst, szName, dim(szName) ); 


// Open the AutoStartOnConnect key. 

re = CeSvcOpen (CESVC_ROOT_MACHINE, “AutoStartOnConnect", 
TRUE, &hSvc); 

if (rc == NOERROR) { 
// Write the module name into the registry. 
CeSvcSetString (hSvc, TEXT ("MyCompanyMyApp™), szName) ; 
CeSvcClose (hSvc); 

} 

return rc; 


The routine above doesn’t have to know the absolute location of the Windows CE 
Services keys in the registry, only that the AutoStart key is under CESVC_ 
ROOT_MACHINE. You can modify this routine to have your application started when 
a connection is broken by substituting AutoStartOnConnect with AutoStartOn- 
Disconnect in the call to CeSvcOpen. 
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COM Method 


As I mentioned before, the COM method of connection notification is implemented 
using two COM interfaces—JDccMan and IDccManSink. The system implements 
IDccMan, while you are responsible for implementing IDccManSink. The IDccMan 
interface gives you a set of methods that allow you to control the link between the 
PC and the Windows CE device. Unfortunately, most of the methods in JDccMan aren't 
currently implemented. The JDccManSink interface is a series of methods that are 
called by the connection manager to notify you that a connection event has occurred. 
Implementing each of the methods in IDccManSink is trivial because you don’t need 
to take any action to acknowledge the notification. 

The process of connection notification is simple. You request an [DccMan in- 
terface. You call a method in IDccMan to pass a pointer to your IDccManSink inter- 
face. Windows CE Services calls the methods in JDccManSink to notify you of events 
as they occur. In this section, I’ll talk about the unique methods in IDccManSink and 
IDccMan, but I'll skip over the JUnknown methods that are part of every COM inter- 
face. For a very brief introduction to COM, read the sidebar, “COM Isn’t a Four-Letter 
Word” at the end of this chapter and the Appendix, “COM Basics.” 


The [DccMan interface 

To gain access to the [DccMan interface, you need to call the COM library function 
Colnitialize to initialize the COM library. Then you make a call to CoCreateInstance 
to retrieve a pointer to the JDccMan interface. Once you have this interface pointer, 
you call the method IDccMan::Advise to notify the connection manager that you want 
to be notified about connection events. This method is prototyped as 


HRESULT IDccMan::Advise (IDccManSink *pDccSink, 
DWORD *«pdwContext); 


The first parameter is a pointer to an IDccManSink interface that you must have pre- 
viously created. Pll talk about DccManSink shortly. The second parameter is a pointer 
to a DWORD that receives a context value that you pass to another JDccMan method 
when you request that you no longer be advised of events. 

You can display the communications configuration dialog of Windows CE Ser- 
vices by calling this method: 


HRESULT IDccMan::ShowCommSettings (void); 


There are no parameters. This method simply displays the communications dialog 
box. The user is responsible for making any changes to the configuration and for 
dismissing the dialog box. 
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When you no longer need connection notifications, you call the Unadvise 
method, prototyped as 


HRESULT IDccMan::Unadvise (DWORD dwContext); 


The only parameter is the context value that was returned by the Advise method. After 
you have called Unadvise, you no longer need to maintain the JDccManSink interface. 


The [DccManSink interface 

You are responsible for creating and maintaining the IDccManSink interface for as 
long as you want notifications from the connection manager. The interface methods 
are simple to implement—you simply provide a set of methods that are called by the 
connection manager when a set of events occurs. Following are the prototypes for 
the methods of IDccManSink: 


HRESULT IDccManSink::OnLogListen (void); 

HRESULT IDccManSink::OnLogAnswered (void); 

HRESULT IDccManSink::OnLogIpAddr (DWORD dwIpAddr); 
HRESULT IDccManSink::OnLogActive (void); 

HRESULT IDccManSink::OnLogTerminated (void); 
HRESULT IDccManSink::OnLogInactive (void); 

HRESULT IDccManSink::OnLogDisconnection (void); 


HRESULT IDccManSink::OnLogError (void); 


While the documentation describes a step-by-step notification by the connection 
manager, calling each of the methods of IDccManSink as the events occur, I’ve found 
that only a few of the methods are actually called with any consistency. 

When you call CoCreateInstance to get a pointer to the IDccManSink interface, 
the connection manager is loaded into memory. When you call Advise, the connec- 
tion manager responds with a call to OnLogListen, indicating that the connection mana- 
ger is listening for a connection. When a connection is established, the connection 
manager calls OnLogIpAddr to notify you of the IP address of the connected device. 
OnLoglpAdar is the only method in IDccManSink that has a parameter. This parame- 
ter is the IP address of the device being connected. This address is handy if you want 
to establish a socket connection to the device, bypassing the extensive support of 
the connection manager and RAPI. This IP address can change between different 
devices and even when connecting the same device if one connection is made using 
the serial link and a later connection is made across a LAN. The connection manager 
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then calls OnLogActive to indicate that the connection between the PC and the de- 
vice is up and fully operational. 

When the connection between the PC and the Windows CE devices is dropped, 
the connection manager calls the OnLogDisconnection method. This disconnection 
notification can take up to a few seconds before it’s sent after the connection has 
actually been dropped. The connection manager then calls the OnLogListen method 
to indicate that it is in the listen state, ready to initiate another connection. 

Some of the other methods are called under Windows 98. Those methods sim- 
ply refine the state of the connection even further. Since your application has to op- 
erate as well under Windows NT as it does under Windows 98, you'll need to be able 
to operate properly using only the notifications I’ve just described. 


The CnctNote Example Program 


The CnctNote program is a simple dialog box—based application that uses the COM- 
based method for monitoring the PC-to-Windows CE device connection state. The 
example doesn’t act on the notifications—it simply displays them in a list box. The 
source code for CnctNote is shown in Figure 11-7. 


Figure 11-7. CnctNote source code. (continued) 
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(continued) 
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Figure 11-7. continued 
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(continued) 
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The meat of CnctNote is in the WM_SIZE handler of the window procedure. 
Here, CoCreatelnstance is called to get a pointer to the JDccMan interface. If this is 
successful, an object is created that implements an JDccManSink interface. The 
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Advise method is then called to register the IDccManSink object. The sole job of the 
methods in JIDccManSink is to report when they’re called by posting a message in 
the list box, which is the only control on the dialog box. 


Connection Detection on the Windows CE Side 


As you know, this chapter describes the PC-side applications that work with remote 
Windows CE devices. However, while reading the previous section, you probably 
wondered how a Windows CE application can know when a connection is made 
between the Windows CE device and a PC. 

Windows CE supports a unique API known as the Notification API. While 
I'll describe this API fully in the next chapter, a quick mention of one function, 
CeRunAppAtEvent, which provides Windows CE applications the ability to be noti- 
fied when a connection is made, wouldn’t hurt. CeRunAppAtEvent registers an appli- 
cation with the system so that it can be launched when a specified event occurs in 
the system. Such events include when the system time is changed, when a system is 
restored from a backup, and yes, when a connection is made to a PC. This function 
is prototyped as 


BOOL CeRunAppAtEvent (TCHAR *pwszAppName, LONG IWhichEvent) ; 


The first parameter is the name of the application to be launched when the event oc- 
curs. The second parameter is a set of bit flags that indicate which events you want to 
monitor. A number of flags are related to various events in the system. For the moment, 
I'll mention two: APP_RUN_AT_RS232_ DETECT and APP_RUN_AFTER_SYNC. These 
flags launch the specified program after a connection is detected and after the synchro- 
nization process has completed. | 

When the application is launched by the notification system, a predefined string 
is passed to the application on the command line. For an application launched due to 
an RS232 detection, the command line string is AppRunAtRs232Detect. For an applica- 
tion launched at the end of synchronization, the command line is AbpRunAfterSync. 
For a complete description of this function and the other notification functions, refer to 
Chapter 12. 


FILE FILTERS 


680 


Windows CE file filters are COM objects that exist on the PC. They’re loaded and called 
by Windows CE Services. When a file is copied to or from the Windows CE device to 
the PC using Windows CE Services, it checks to see whether a file converter is regis- 
tered for the file type being transferred. If so, the file filter is loaded and requested to 
convert the file. All this takes place on the PC side of the link. If a file is being moved 
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from the Windows CE system to the PC—exported, in Windows CE-speak—it’s 
copied in its original form to the PC, then converted by the file filter, and finally stored 
on the PC. Likewise, if a file is being imported to the Windows CE device, it’s first 
converted and then copied to the Windows CE device. 

Windows CE file filters are tied closely to the Mobile Devices folder. Only files 
moved to and from a Windows CE device by users dragging and dropping them in 
the Mobile Devices folder are converted. If a file is transferred to a Windows CE sys- 
tem by any other method, accessing a file through the Windows CE LAN redirector, 
for example, the file filter isn’t loaded and file won’t be converted. Likewise, if a file 
is downloaded from the Internet using Pocket Inbox, the file won’t be converted. 


Registering a File Filter 


Windows CE Services knows about file filters by looking in the registry. File filters 
need to be registered in two places. First, file filters should be among the Windows 
CE Services entries for each registered device under HKEY_CURRENT_USER. Second, 
they should be registered under the Windows CE Services entries under HKEY_ 
LOCAL_MACHINE so that each filter will: be automatically registered for any new 
devices that link to the PC. The CeUtil functions are helpful when you're registering 
a file filter because they handle opening the proper subkeys in which you register 
the file filter. | 

In addition to registering the file filter itself, you must make a few other new 
entries in the registry. The COM server that implements the file filter must be regis- 
tered under [HKEY_CLASSES_ROOT]\CLSID. This registration follows the standard 
format for a COM object with a few extensions I'll describe in a moment. In addition 
to registering the COM object, you must also register the file extensions for both the 
PC file type and the file type for the Windows CE version of the file. 

To sum up, a file filter needs to make a number of changes in the registry to 
properly function. For example, the program that installed the Pocket Word converter, 
which changes DOC format files used by Microsoft Word to the Pocket Word format 
PWD used by Pocket Word, must first register the PWD file type under [HKEY_ 
CLASSES ROOT]. You do this with two entries: one to associate the file extension 
with a file type and another entry to associate the file type with its name and the default 
shell actions. For the Pocket Word files, the entries look like this: 


[HKEY_CLASSES_ROOT]\ . pwd pwdfile 
and 
[HKEY_CLASSES_ROOT]\pwdfile Pocket Word File 
DefaultiIcon c:\Program Files\Windows CE Services\minshel1.d11,-204 
Shel] 
Open c:\Program Files\Microsoft Office\Office\WinWord.exe 
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The Windows CE file type must be registered on the PC even though this file 
type generally exists only on a Windows CE system. 

The DOC file type, which is the PC-side file type of the Pocket Word file filter, 
is already registered on Windows-based PCs, but if you introduce a new file type for 
the PC side of your converter it, too, must be registered. 

The COM object that implements the Pocket Word file filter is registered in an 
entry under the [HKEY_CLASSES_ROOT]\CLSID key. The key name is the CLSID for 
the COM server that provides the file filter. Underneath this key are entries for the 
object’s icon and the location of the DLL that provides this class ID. For Pocket Word, 
the entry looks like this: 


[HKEY_CLASSES_ROOTJ\CLSID\{4D3E2CF2-9B22-11D@-82A3-Q@0AA00C267C1} 


DefaultIcon c:\Program Files\Windows CE Services\pwdcnv.d11,@ 
InProcServer32 c:\Program Files\Windows CE Services\pwdcnv.d11 
ThreadingModel Apartment 
PegasusFilter 
Description Pocket Word 2.@ Document 
Import 
NewExtension . pwd 


The long series of numbers in the key name is the GUID for the PWD file filter. 
Each object will have a unique GUID that matches the GUID the object checks for 
when the DilGetClassObject call is made. The DefaultIcon and InProcServer32 keys 
are standard for all COM object servers. The PegasusFilter key is unique to Windows CE 
file filters. This key contains the Description and NewExtension values that give you 
the extension and description of the resulting file type of the converter. The Import 
value indicates that this file filter will be converting files copied from the PC to the 
Windows CE device. If this filter converted Windows CE format files to PC format 
files it would have a value named Export under the PegasusFilter key. 

Now that the file types and the filter DLL itself have been registered, all that 
remains is to register the filter with Windows CE Services so that it will be called when 
a file is copied to or from the Windows CE device. To register the filter so that it will 
be used on guest devices and all future devices, you add a key with the name of the 
destination file extension under the key [HKEY_LOCAL_MACHINE]\Software 
\Microsoft\Windows CE Services\Filters. Under this key, you add entries that asso- 
ciate the import and export action with the CLSID of the COM server that implements 
the filter. 

The file extension that you register is the extension of the source file, whether 
it's being imported to the Windows CE device or exported to the PC. So a Word 
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document file with the extension DOC wouldn’t require any conversion when cop- 
ied up to a PC, but would need to be converted to the pocket word (PWD) format 
when it’s copied from the PC to the Windows CE. The entry that registers a filter to 
convert DOC files to PWD format looks like this: 


[HKEY_LOCAL_MACHINE]\Software\Microsoft\Windows CE Services\Filters\.DOC 


DefaultExport Binary Copy 
DefaultImport {4D3E2CF2-9B22-11D0-82A3 -@0AA00C267C1 } 
InstalledFilters 


{4D3E2CEC - 9B22-11D0-82A3-Q@QAAQ0C267C1} 
{4D3E2CED-9B22-11D0-82A3-Q@@AAQ0C267C1} 
{4D3E2CF2-9B22-11D0-82A3-Q@0AAQ0C267C1} 


{4D3E3068 -9B22-11D0-82A3-@@AAQ0C267C1} 


This entry registers filters for all files with the DOC file extension. When the file 
is imported to the Windows CE device, the filter used is contained in the COM server 
with the CLSID of 4D3E2CF2-9B22-11D0-82A3-00AA00C267C1. When a DOC file is 
exported from the Windows CE device to the PC, no conversion is needed, so the 
placeholder Binary Copy is used in place of a CLSID. When Windows CE Services 
sees this, it simply copies the file without modification. If this entry isn’t in the regis- 
try, Windows CE Services thinks no filter is registered for this file type and displays a 
warning to the user when the file is copied. In this case, we don’t want to convert a 
DOC file when it’s being exported from the Windows CE device, so the registry has 
a Binary Copy flag entry for this entry. 

Under the InstalledFilters key, you place one or more CLSIDs for different fil- 
ters. Pocket Word for example, has a number of filters to convert PWD files into 
Word 97 documents, Word 95 documents, Word Perfect documents, and such. All these 
selections are presented to the user in the File Conversion dialog box that can be 
displayed from the Mobile Devices window on the PC. 

One limitation of the current registry setup for file filters is that the same CLSID 
can’t be defined to perform both the import and export conversions on a file. This is 
because the destination file extension is taken from the registry entries under the CLSID 
key. You can, however, have one COM server that supports two CLSIDs that, in turn, 
create the appropriate filters for each CLSID. 

In addition to registering the file filter generically, you need to register the filter 
for any devices that already have a partnership with the PC. Otherwise, these devices 
won't use your filter. To do this, you need to repeat the registration procedures just 
described in this section under the key [HKEY_CURRENT_USER]\Software\ Microsoft 
\Windows CE Services\Partners\<<Device ID>>\filters. 
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You register the file filter for a specific device the same way you register the 
filter generically: by specifying the filter under its file extension. 
In the key on the preceding page, the <<Device ID>> placeholder should be 


replaced with the device ID of each of the devices for which you want to register the 


filter. This is where the CeUtil functions come in handy. Using CeSvcEnumDevices, 
you can specify each device and then open the proper key using CeSucOpen. So for 
the remainder of this section, I’ll use the CeSuc functions provided by the CeUtil li- 
brary to abstract the keys instead of talking about the proper registry keys in terms of 
their absolute key names. 

To open the registry key where filters are located, you would use the CeSucOpen 
function and pass the constant CESVC_FILTERS. In the subkey name parameter, you 
would pass the extension of the file filter, as in 


hr = CeSvcOpen (CESVC_FILTERS, [Lyour file extension]], 
TRUE, &hSvc); 


To carry on our example, the key for the Pocket Word converter would be 
opened this way: 


hr = CeSvcOpen (CESVC_FILTERS, TEXT (".pwd"), TRUE, &hSvc); 


Once the key is opened, you can use CeSucSetString to write the specific en- 
tries in the registry. 

In the routine below, a file filter is registered both generically and under each 
currently registered device. The routines below use the CeSvcxxx functions, although 
you could use standard registry functions if you feel the need. 


// RegExtensionforDevice - Helper routine that registers the filter for 
// one device 
// 
HRESULT RegExtensionforDevice (HCESVC hSvc, LPTSTR pszGUID, 
LPTSTR pszExt, BOOL bImport) { 

TCHAR szTag[32]; 

HCESVC hKey; 

HRESULT hr; 


if (bImport) 
Tstrcpy (szTag, TEXT ("DefaultImport")); 
else. 
Istrcpy (szTag, TEXT ("DefaultExport")); 
CeSvcSetString (hSvc, szTag, pszGUID); 
hr = CeSvcOpenEx (hSvc, TEXT ("InstalledFilters"), TRUE, &hKey); 
if (hr) return hr; 
CeSvcSetString (hKey, pszGUID, TEXT ("")); 


return hr; 
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// RegFileExtension - This routine registers a file extension for all 
// currently partnered devices as well as for guest devices. 
// 
HRESULT RegFileExtension (LPTSTR pszGUID, LPTSTR pszExt, BOOL bImport) { 
~ HRESULT hr; 
HCESVC hSvc, hDev, hDevFilterKey; 
DWORD dwPro, i = @; 
TCHAR szKeyName[64]; 


// Open generic filter key. 
hr = CeSvcOpen (CESVC_FILTERS, pszExt, TRUE, &hSvc); 
if (hr) 
return hr; 
// Call routine to fill in proper keys. 
hr = RegExtensionforDevice (hSvc, pszGUID, pszExt, bImport); 
CeSvcClose (hSvc); 


// Now register for each current partner. 
while (CeSvcEnumProfiles (&hSvc, i++, &dwPro) == 0) { 


// Open key for that partner. 
hr = CeSvcOpen (CESVC_DEVICEX, (LPTSTR)dwPro, FALSE, &hDev); 


if (hr) { 
CeSvcClose (hSvc); 
return hr; 

} 


// Open filter key underneath. 

Istrcepy (szKeyName, TEXT ("Filters\\")); 

Istrcat (szKeyName, pszExt); 

hr = CeSvcOpenEx (hDev, szKeyName, TRUE, &hDevFilterKey) ; 


// Close this key since we don't need it anymore. 
CeSvcClose (hDev); 


if (hr) { 
CeSvcClose (hSvc); 
return hr; 

} 


// Call routine to fill in proper keys. 
hr = RegExtensionforDevice (hDevFilterKey, pszGUID, pszExt, 
bImport); 
// Close filter\extension key. 
CeSvcClose (hDevFilterKey); 
} 


return hr; 
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To register a file filter with the routines, you would call RegFileExtension. This 
routine first calls RegExtensionforDevice to register the file filter for future partners 
under HKEY_LOCAL_MACHINE. Then the routine enumerates each currently registered 
partner and registers the filter for those devices. The GUID and file extension for 
RegFileExtension are passed as strings. An example call would be 


RegFileExtension ("{2b06f7al-088e-11d2-93f1-204c4f4f5020}", 
"\tst", TRUE); 


For the other parts of the registry initialization, registering file extensions and 
registering the class library, a simple REG file will do. A REG file is a text file that 
contains the keys and values to merge into the registry. Following is an example 
REG file that registers a class library for converting TST files into PTS files on the 
Windows CE device. 


REGEDIT4 


[THKEY_CLASSES_ROOT\CLSID\ {2b06f7a1 -088e-11d2-93f1-204c4f4f5020} ] 
@="CEFileFilter Example" 

[HKEY_CLASSES_ROOT\CLSID\{2b06f7al -088e-11d2-93f1-204c4f4f5020}\DefaultIcon] 
@="TstFilt.d11,-100" 
[HKEY_CLASSES_ROOT\CLSID\ {2b06f7al -088e-11d2-93f1-204c4f4f5020}\InProcServer32 ] 
@="e:\\CEBOOK\\11. Connecting to the Desktop\\TstFilt\\Debug\\TstFilt.d1l1" 
"ThreadingModel "="Apartment"” 
[HKEY_CLASSES_ROOT\CLSID\ {2b06f7al -988e-11d2-93f1-204c4f4f5020}\PegasusFilter] 
"Import"="" 

"Description"="TstFilt: Copy a .tst file with no conversion." 
"NewExtension"="pts" 


[LHKEY_CLASSES_ROOT\.tst] 

@="tstfile" 

[HKEY_CLASSES_ROOT\tstfile] 

@="TstFilt: Desktop TST File” 

[HKEY_CLASSES_ROOT\tstfile\DefaultIcon] 

@="e:\\CEBOOK\\11. Connecting to the Desktop\\TstFilt\\Debug\\TstFilt.d1l1,-100" 
[HKEY_CLASSES_ROOT\ptsfile] 

@="TstFilt: HPC TST File” 

LHKEY_CLASSES_ROOT\ptsfile\DefaultIcon] 

@="e:\\CEBOOK\\11. Connecting to the Desktop\\TstFilt\\Debug\\TstFilt.d1l1,-101" 


Now that we’ve learned how to register a file filter, let’s look into building one. 
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The File Filter Interfaces 


Windows CE file filters are COM in-proc servers that export an [CeFileFilter interface. 

The filter can also optionally export an ICeFileFilterOptions interface. Mobile Devices 

indirectly calls these two interfaces using the OLE object manager when it needs to 

convert a file. When stripped of all the COM paraphernalia, implementing a file filter 

is nothing more that implementing three functions, two of which are quite trivial. 
The ICeFileFilter interface has the following methods: 


B ICeFileFilter::NextConvertFile Called to convert a file 


M ICeFileFilter::FilterOptions Called to display a dialog box for filter options 
during setup 


M ICeFileFilter::-FormatMessage Called to convert an error code into a text 
message to be displayed to the user 


ICeFileFilter::NextConvertFile 
The primary method of a file filter is NextConvertFile. This method is called by the 
Mobile Devices program when a file needs to be converted from its PC format to its 
Windows CE format or the reverse. The method actually keeps being called until you 
tell it to stop. This allows a file filter to create multiple output files for every input file 
it converts. | 

The prototype for this method is 


HRESULT ICeFileFilter: :NextConvertFile (int nConversion, 
CFF_CONVERTINFO *pci, 
CFF_SOURCEFILE «psf, 
CFF_DESTINATIONFILE *pdf, 
volatile BOOL *pbCancel, 
PR_ERROR *perr); 


The first parameter, mConversion, is a count value that’s incremented each time the 
method is called for a single file. This means that the first time NextConvertFile is called 
to convert the file FOO.BAR, nConversion is 0. After you return from NextConvertFile, 
Mobile Devices calls NextConvertFile again, specifying the same input file, FOO.BAR, 
and the nConversion parameter is set to 1. Most file filters simply return the error code 
ERROR_NO_MORE_ITEMS, which tells Mobile Devices that you’ve completed con- 
verting the file. On the other hand, you can continue to process the conversion of 
FOO.BAR in the second, third, and subsequent calls. Mobile Devices continues to call 
NextConvertFile, specifying the same input file until you return ERROR_NO_ 
MORE_ITEMS. 


687 


Part Ill 


The next parameter, pci, is a pointer to a CFF_CONVERTINFO structure, which 
give you general information about the conversion as well as providing a pointer to 
the [CeFileFilterSite interface. The structure looks like this: 


typedef struct { 
BOOL bImport; 
HWND hwndParent; 
BOOL bYesToAl1; 
ICeFileFilterSite «pffs; 
} CFF_CONVERTINFO; 


The first field, bImport, is set to TRUE if the file is being copied from the PC to the 
Windows CE device. The hwndParent parameter is the handle of a window that you 
can use as the parent window for any dialog boxes that need to be displayed. The 
bYesToAll field should be set to TRUE if you’re copying more than one file. This flag 
indicates whether the Yes To All button is displayed in the overwrite files dialog box. 
Finally, the pffs field contains a pointer to an [CeFileFilterSite interface. This interface 
provides the functions used by the file filter to open and close the source and desti- 
nation files. 
ICeFileFilterSite has the following methods: 


ICeFileFilterSite::OpenSourceFile Opens the source file 
ICeFileFilterSite::OpenDestinationFile Opens the destination file 


ICeFileFilterSite::CloseSourceFile Closes the source file 


ICeFileFilterSite::CloseDestinationFile Closes the destination file 


ICeFileFilierSite::ReportProgress Updates the modeless dialog box that 
indicates the progress of the conversion 


ICeFileFilterSite::ReportLoss Causes a dialog box to be displayed that 
reports to the user that data was lost in the conversion 


The OpenSourceFile and OpenDestinationFile methods of ICeFileFilterSite re- 
turn pointers to [Stream or [Storage interfaces that are used to read and write these 
files. The [Stream interface is used if the file is opened as a standard flat file while the 
IStorage interface is returned if the file is opened as an OLE compound document. 

The next parameter of NextConvertFile, psf, is a pointer to a CFF_SOURCEFILE 
structure that gives you information about the source file used in the conversion. The 
structure is defined as 


typedef struct { 
TCHAR szFullpathL_MAX_PATH] ; 
TCHAR szPath[_MAX_PATH] ; 
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TCHAR szFilename[_MAX_FNAME]; 
TCHAR szExtension[L_MAX_EXT]; 
DWORD cbSize; 
FILETIME ftCreated; 
FILETIME ftModified; 

} CFF _SOURCEFILE; 


The szFullPath field contains the fully qualified filename of the source file. The 
next three fields contain the parsed components of the same name. The cbSize pa- 
rameter contains the size of the source file, while the /ftCreated and ftModified fields 
contain the time the file was created and last modified. 

The pdf parameter points to a CFF_DESTINATIONFILE that defined the particu- 
lars of the recommended destination filename. The structure is defined as 


typedef struct { 
TCHAR szFullpath[_MAX_PATH]; 
TCHAR szPath[_MAX_PATH]; 
TCHAR szFilename[L_MAX_FNAME]; 
TCHAR szExtension[_MAX_EXT]; 
} CFF_DESTINATIONFILE; 


The structure has the same first four fields as the CFF_SOURCEFILE structure. 
The difference is that the name in the CFF_DESTINATIOMNFILE structure is a recom- 
mended name. You can override the name of the destination file in the Open- 
DestinationFile method of /CeFileFilterSite. To do this, use the suggested path of 
the destination file contained in szPath and append the name and extension with 
the suggested modifications. Pass this new name to the pszFullPath parameter in 
OpenDestinationFile. The file filter example at the end of the chapter uses this tech- 
nique to rename the destination file. 

The next parameter of NextConvertFile is pbCancel, a pointer to a BOOL. The 
pbCancel parameter points to a boolean that is changed to FALSE if the user pressed 
the Cancel button on the modeless dialog box that’s reporting the progress of the 
conversion. The file filter must check this value periodically to see whether the user 
has canceled the conversion. 

The last parameter, perr, points to an error value that’s returned by the 
NextConvertFile method. If NextConvertFile returns the error code E_FAIL, the value 
pointed to by perr is used as the error code for the routine. This code is then passed | 
back to the filter for interpretation when you call FormatMessage. 


ICeFileFilter::FormatMessage 

The FormatMessage method closely follows the syntax of the FormatMessage system 
call that formats messages using an error code and either the system message table 
or a string table from a module. For many uses, you can simply pass the call directly 
from [CeFileFilter::FormatMessage to the Win32 function FormatMessage. 
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ICeFileFilter:: FormatMessage has the prototype 


HRESULT ICeFileFilter::FormatMessage (DWORD dwFlags, 
DWORD dwMessageld, 
DWORD dwLanguageld, LPTSTR IpBuffer, 
DWORD nSize, va_list *Arguments, 
DWORD pcb); 


While the parameter list looks daunting, the best way to handle this method is to create 
a message resource in the filter and pass the call directly to Win32’s FormatMessage 
with the addition of the flag FORMAT_MESSAGE_FROM_HMODULE to the dwFlags 
parameter. The only additional processing is to copy the number of bytes returned 
by Win32’s FormatMessage and set the byte count in a variable pointed to by the 
parameter pcb. An example would be 


// FormatMessage - Called to format error messages 
// 
STDMETHODIMP MyFileFilter::FormatMessage (DWORD dwFlags, 
DWORD dwMessageld, DWORD dwLanguageld, 
LPTSTR 1lpBuffer, DWORD dwSize, 
va_list «args, DWORD pcb) { 
DWORD cMsgLen; 


// Pass the error code on to the Win32 FormatMessage. Force look 
// into message table of filter by ORing dwFlags with 
// FORMAT_MESSAGE_FROM_HMODULE. 
cMsgLen = ::FormatMessage (dwFlags | FORMAT_MESSAGE_FROM_HMODULE, 
hInst, dwMessageld, dwLanguageld, 
IpBuffer, dwSize, args); 
if (cMsgLen) 
*pcb = cMsgLen; 
else 
return E_FAIL; 


return NOERROR; 


If you’re going to use custom filter error messages, you should define them using 
a constant combined with the macro CF_DECLARE_ERROR. T his macro ensures that 
the error value you choose won’t conflict with the standard Win32 error constants. _ 
In addition to defining the constants, you associate a string with the constant by 
including a message table resource in your filter. This, combined with the FORMAT_ 
MESSAGE_FROM_HMODULE flag when you're calling Win32’s FormatMessage, causes 
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your message text to be used for your error constants. If the error value returned isn’t 
one you defined, FormatMessage then looks in the system message table for a matching 
error message. 


ICeFileFilter::FilterOptions 
The final method of /CeFileFilter is FilterOptions. This method is prototyped as 


HRESULT IPegasusFileFilter::FilterOptions (HWND hwndParent); 


The only parameter is a handle to a window that should be used as the parent win- 
dow for the dialog box. Windows CE Services calls this method when the user re- 
quests that the Options dialog box be displayed. However, none of the current versions 
of Windows CE Services support this Options button—so while you need to support 
this method, you can’t depend on the user being able to gain access to any dialog 
box displayed by this method. 


The [CeFileFilterOptions Interface 


Windows CE file filters can support one other interface, /CeFileFilterOptions. This 
interface has, aside from the JUnknown methods, only one method: SetFilterOptions. 
The SetFilterOptions method enables Windows CE Services to tell the file filter whether 
it can display a modal dialog box during the conversion process. This is necessary 
because some conversions might take place in the background, where such displays 
of dialog boxes wouldn’t be appropriate. 

SetFilterOptions is prototyped as 


HRESULT SetFilterOptions (CFF_CONVERTOPTIONS* pco); 


The only parameter is a pointer to a CFF_CONVERTOPTIONS structure, which is 
defined as 


typedef struct { 
ULONG cbSize; 
BOOL DNoModalUI; 
} CFF_CONVERTOPTIONS; 


While it may seem that using a structure to pass one Boolean is overkill, the use of a 
structure with a size field at the start lets Microsoft think about extending this struc- 
ture while remaining backward compatible with older file filters. 


The DivFile Filter Example 


The example shown on the next page is a Windows CE file filter that detects when 
the user is copying files larger than 100 KB to a Windows CE device and splits the file 
into separate files on that device. If the file is larger than 100 KB and the version of 
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Windows CE is earlier than 2.1, the DivFile filter splits the file into multiple parts so 
that it can be stored in the object store of the device. Although the actual limit for 
files in Windows CE 2.0 and earlier is 4 MB, the 100-KB limit gives you an opportu- 
nity to see the splitting in action without having to wait for a file larger than 4 MB to 
be copied across to a Windows CE device. 

The filter defines two new file types, TST for a file on the PC and PTS for pocket 
test, a sample file type on a Windows CE device. For this example, the splitting func- 
tion is performed only on TST files larger than 100 KB. The result is a series of files 
on the Windows CE device, each with a number appended to the original filename 
and a new file type of PTS. The PTS files can be copied back to the PC unaltered and 
then rejoined using a binary copy operation, as in 


copy /b file_l.ptst+file_2.ptst+file_3.ptst+file_4.pts original.tst 


The first file in this example isn’t a source or include file; it’s a registry file that 
registers the file filter, DivFile.reg. Note that since I’m not using an install program 
that can enumerate the various Windows CE devices already partnered, this filter won’t 
be used until a new device is partnered with the PC or a device is attached as a guest 
of Windows CE Services. Also, the Explorer doesn’t recognize the new file types until 
the system is rebooted—or more precisely, until the desktop is restarted. DivFile.reg 
is shown in Figure 11-8. 


Figure 11-8. 7he DivFile.reg file filter. 
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The registry file shown here uses the path to the copy of the DivFile.dll on my 
machine; you’ll need to modify the path for your machine. Also, the GUID I gener- 
ated should be replaced with one you create using GUIDGEN.EXE. The lines in this 
registry file are grouped into four sections. The first section registers the COM server 
DLL, DivFile.DLL. The second and third groups of lines register the file types TST and 
PTS. Finally, the last group of lines registers the file filter in the generic section of 
Windows CE Services’ entries in the registry. You could easily write an install pro- 
gram to automatically register the file filter with the currently partnered Windows CE 
devices, using the routines I presented earlier in the chapter. 

The next file in the example is DivFile.def. The def file describes the exported 
functions from the DLL. I don’t use the declspec macro used in the earlier examples 
here because of the predefined type definitions of the functions DilGetClassObject 
and DilCanUnloadNow. Figure 11-9 shows DivFile.def. 


Figure 11-9. Zhe DivFile.def program. 


Finally, we get to the source files for the example, DivFile.rc, DivFile.h, and 
DivFile.cpp shown in Figure 11-10 on the following page. The resource file declares 
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Figure 11-10. continued 
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The code that does the actual work of the file filter is contained in NextConvert- 
File. The routine uses the value in nConversion to see whether this is the first time it 
is being called to convert the file. If so, the routine checks the file size to see whether 
it’s bigger than the arbitrary file size limit. If so, the user is asked if the file should be 
split into multiple files. 

The routine creates individual destination files by specifying a new name for the 
destination file when the routine calls OpenDestinationFile. For files that are split, the 
routine generates each new filename by appending a number to the end of the original 
filename. Note that the routine takes care to preserve the suggested path for the des- 
tination file. This path specifies the temporary directory on the PC that Windows CE 
Services uses before copying the converted file down to the Windows CE device. At 
this point, the source file is copied to the new destination file up to the limit of the 
destination file size. The files are then closed, and NextConvertFile returns. 

Windows CE Services calls NextConvertFile again, this time with nConversion 
incremented. The routine opens a new destination file and the old source file, then 
seeks to an offset in the source file that matches the last byte read in the previous 
call. The new data is then copied, and the routine again returns. 

This process of calling NextConvertFile is continued until the routine determines 
that all the source file has been copied into the various destination files. At this point, 
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the routine returns ERROR_NO_MORE_ITEMS, which ends the conversion process 
for the file. 

Now I come to the end of my explanation of the PC-side Windows CE Services. 
In the next two chapters, I’ll return to the Windows CE-side of things to look at the 
shell. The Windows CE shell varies widely across the different platforms. The Handheld 
PC shell looks on the surface like a standard Windows 95 shell, although the pro- 
gramming interface is much simpler. The Palm-size PC shell, on the other hand, is 
new and unique. 


COM ISN’T A FOUR-LETTER WORD 


At this point, I’ve written 705 pages in a modern Windows programming book, 
and I have yet to explicate COM. It’s amazing in this day and age that we’ve 
actually programmed almost an entire Windows system without COM. That 
avoidance ends here because COM is used extensively on the PC side of the 
Windows CE data synchronization interfaces. 

COM is the acronym for Component Object Model. In brief, COM is for- 
mally defined as a binary standard for defining objects. The classical definition 
of an object is data surrounded by a collection of functions, usually called 
methods, which act on the data. Sometimes people stretch this classical object 
definition when they talk about COM. It works out that the only internal data 
state that some COM objects have is a use count variable. That kind of COM 
object simply provides an interface that’s used for some purpose or another. 
Plenty of COM objects do maintain some internal data but this condition isn’t a 
requirement of a COM object. 

Many people have written and argued about COM. Various program- 
mers think of COM as the Second Coming, the ultimate programming concept, 
or even the key to World Peace. On the other hand, others think of COM as the 
devil incarnate, a complex unworkable mess, or most evil of all, a way to keep 
dozens of authors employed writing books trying to explain it. In my mind, COM 
is simply a tool. Many books have been written about COM, but only one, 
Mr. Bunny’s Guide to Active X, captures the essence of COM. Check it out if 
you get the opportunity. 

In the Appendix, “COM Basics,” I touch ever so lightly on the subject of 
COM. I talk only about a few interfaces, and then only to the extremely shallow 
depth necessary to accomplish our task at hand, synchronizing data between a 
PC and a Windows CE device. This treatment doesn’t do justice to COM nor is 
it meant to. I’m just trying to use a tool to accomplish a job. 
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Shell Programming 
—Part 1 


One of the unique aspects of Windows CE is that different Windows CE platforms 
have different shells. The shell for the Handheld PC is significantly different from the 
shell for the Palm-size PC. Despite differences, the parts of the shell that are the same 
(and there are plenty of common shell components), share the underlying API. 

The shells used by the H/PC and H/PC Pro derive from the Windows 95 and 98 
shells. To the user, the look is almost pure Windows 95. That is, of course, by design. 
The folks at Microsoft figured that having the Windows CE shell resemble the Win- 
dows 95 shell would flatten the user’s learning curve and enhance the acceptability 
of Windows CE devices. 

The shell used by the Palm-size PC keeps some of the more basic aspects of 
the Windows 95 shell. Gone are the Explorer and the familiar desktop icons. In place 
of the Explorer is the Active Desktop, which displays data from applications directly 
on the desktop. But while the Explorer is gone, the taskbar, with its familiar Start 
button, remains. The interface for the taskbar, common to both desktops, is the same. 
Both systems also use special directories and the shell namespace, which I'll talk 
about shortly. 

So although the Windows CE shell resembles the Windows 95 shell, it’s not as 
flexible. Most of the powerful interfaces available under Windows 95, such as the ability 
to drag and drop objects between programs, are either only partially implemented or 
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not implemented at all. The goal of the programmers of the Windows CE 2.0 shell 
seemed to be to implement as few of the native COM interfaces as possible while 
still retaining the ability to contain the Internet viewing capabilities of an embedded 
Internet Explorer in the shell. That said, the current Windows CE shell does use 
some COM interfaces. It’s just that those interfaces aren’t the ones available on the 
desktop. 

This chapter covers the concept of the shell namespace and the shell’s use of 
special directories. This chapter also explains how to work with the taskbar as well 
as how to create shortcuts. And although the Notification API and the console aren’t 
strictly part of the shell, this chapter covers them, too. Windows CE provides a pow- 
erful notification interface that allows applications to schedule themselves to run at a 
certain time or when some system event occurs. The code that implements the noti- 
fication API was moved from the shell to the base operating system in Windows CE 2.1. 
This allows the notification functions to be used in the embedded versions of Win- 
dows CE where only a minimal shell is provided. The Windows CE console, on the 
other hand, was introduced in Windows CE 2.1. Windows CE doesn’t support the full 
character mode API found in Windows NT, but you can write fairly complete con- 
sole applications. 

For those of you who are working with the embedded version of Windows CE 2.1 
and later, most of what’s covered in this chapter (with the exception of the Notifica- 
tion API and console applications) won’t help you. The embedded version of Win- 
dows CE 2.1 includes only a bare minimum shell that has neither a taskbar nor an 
Explorer, and doesn’t include many of the DLLs that support the shell. This means 
that you'll have to employ third-party developers or write your own shell to perform 
any shell-like functions. 


WORKING WITH THE SHELL 


Because the H/PC and Palm-size PC shells are derived from the Windows 95 shell, I 
must cover some system definitions first introduced with Windows 95. In general, while 
the concepts remain the same, the implementation is completely different under 
the covers. 


The Shell Namespace 
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From Windows 95 on, the Windows shell has used the concept of a shell namespace. 
The Windows CE shell also uses the namespace concept to track the objects in the 
shell. Simply put, the shell namespace is the entire collection of the operating system’s 
objects, files, directories, printers, control panel applets, and so forth. The idea is that 
by addressing files the same way as control panel applets, the shell makes it easy to 
deal with the diverse collection of objects. 
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A folder is simply a collection of objects. A directory is a collection of files on a 
disk. A folder generalizes and extends the directory concept, in that a folder doesn’t 
merely contain files, but can include other objects such as control panel objects, print- 
ers, or remote connection links. Each object in a folder is called an item. Items are 
identified by an item JID. 

The item ID is a data structure that uniquely identifies the item in the folder. 
Since folders also have identifiers, an individual item can be uniquely defined by means 
of a list of item IDs that identify the item, its folder, and the parent folders of the folder. 
Think of this list of item identifiers as a completely specified pathname of a file. A 
system might have many files named foobar, but only one in a specific directory. This 
list of item IDs is appropriately called an JD list. A pointer to such a list is a pointer to 
an ID list, frequently abbreviated as pidl, which is generally and rather unfortunately 
pronounced piddle. Shell functions usually reference items in the shells by their pidls. 
There is, of course, a translation function that converts a pid/ to a filename. 

With the release of the Palm-size PC, the developers faced a problem. The pid/ 
concept is powerful, but implementing and maintaining pidls didn’t seem worth the 
trouble, given the limited need the Palm-size PC shell has for them. But because some 
of the shell functions use pidls to remain compatible with the H/PC, the Palm-size PC 
has to implement pidls. The solution is for the Palm-size PC shell to “fake” pidls. The 
necessary APIs use a value typed as a pid/ but the actual implementation is a con- 
stant, not a pointer to an item ID list. This strategy doesn’t much affect you as you 
program the Palm-size PC, but you should be aware of it. 


Special Folders 


The Windows CE shell, like the shells for Windows 95 and Windows NT 4.0, has a 
set of folders that are treated differently from normal directories in the file system. 
An example of this is the recycle bin, which is simply a hidden directory to which 
the shell moves files and directories when the user deletes them. Another example 
is the Programs folder, which contains a set of shortcuts that are then displayed on 
the Start menu. 

The list of special folders changes with each shell. The Windows 95, Windows 98, 
and Windows NT 4.0 shells have a different set of special folders from those of the 
Windows CE shells. The shells implemented on the Palm-size PC and H/PC each 
implement their own subset of special folders. Fortunately, the function to return the 
location of a specific special folder is the same on all these systems. That function, 
ShSpecialFolderLocation, is prototyped as 


HRESULT SHGetSpecialFolderLocation (HWND hwndOwner, int nFolder, 
LPITEMIDLIST *ppid1); 
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The first parameter is a handle to a window that owns any dialog box the shell 
needs to display during the processing of this function. The second parameter is a 
constant that specifies the directory you’re requesting. The two main shells for Win- 
dows CE support different subsets of the constants defined by Windows. Below are 
the lists of constants supported by the H/PC and the Palm-size PC. 


On the Handheld PC 
M CSIDI_BITBUCKET ‘The location of the recycle bin. 


M cCSIDL_DESKTOP ‘The folder that stores the objects that appear on the 
desktop. Note that the use of this constant is different than under Win- 
dows 95. 


M cCSIDI_FONTS The folder that contains the system fonts. 


CSIDL_DRIVES The root of the file system. 


BM CSIDIL_PROGRAMS | The folder that contains the items shown in the Pro- 
grams submenu of the Start menu. 


i CSIDL_PERSONAL The default folder in which to save documents. 
wi CSIDL_FAVORITES ‘The folder that contains shortcuts to favorite items. 


M CSIDI_STARTUP The folder that contains programs or shortcuts to pro- 
grams that will be launched when the system is restarted. 


& CSIDL_RECENT ‘The folder that contains the list of recently used docu- 
ments. 


On the Paim-size PC 
M CSIDI_DRIVES The root of the file system. 


= CSIDL_PROGRAMS | The folder that contains the items shown in the Pro- 
grams submenu of the Start menu. 


x CSIDL_STARTUP The folder that contains programs or shortcuts to pro- 
grams that will be launched when the system is restarted. 


M CSIDI_FONTS The folder that contains the system fonts. 
ai CSIDL_FAVORITES ‘The folder that contains shortcuts to favorite items. 


au CSIDL_STARTMENU | The folder that contains the items shown in the Start 
menu. 


| CSIDL_PERSONAL ‘The default folder in which to save documents. 
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The final parameter in SHGetSpecialFolderLocation, pidl, is a pointer to an 
ITEMIDLIST pointer that receives a pointer to the folder’s item ID list. 

The pidl that is returned by SHGetSpecialFolderLocation can be translated to a 
standard file path using this function: 


BOOL WINAPI SHGetPathFromIDList (LPCITEMIDLIST pidl, 
LPTSTR pszPath); 


The two parameters for this function are a pid/ and a pointer to a buffer that receives 
the path of the folder specified by the pidl. This buffer must be at least MAX_PATH 
characters in length. 

If you needed only to call SHGetSpecialFolderLocation and follow that by call- 
ing SHGetPathFromIDList to get the path, life would be simple. Unfortunately, the 
process isn’t that simple. On systems other than the Palm-size PC, the pid/ that’s re- 
turned by SHGetSpecialFolderLocation points to a buffer that has been allocated by 
the shell. You need to call the shell back to free this buffer after you’re finished with 
the ID list. You free this buffer using an JMalloc interface provided by the shell. 

The [Malloc interface contains methods that allow an application to allocate, 
free, and otherwise manipulate memory in the local heap of the ZMalloc provider. In 
the case of the shell, a pointer to its IMalloc interface can be acquired with a call to 
SHGetMalloc. The function is prototyped as— 


HRESULT SHGetMalloc (LPMALLOC *ppMalloc); 


Once you have a pointer to the interface, you can call the Free method to free 
any ID lists returned by ShGetSpecialFolderLocation. On systems other than the Palm- 
size PC, the process can be encapsulated in the following routine: 


INT MyGetSpecialDirectory (HWND hWnd, INT nFolderID, 
LPTSTR IpDir) { 
int rc; 
LPITEMIDLIST pidl; 
LPMALLOC 1pMalloc = NULL; 


// Get the Shell Malloc interface to be able to free the pidls. 
rc = SHGetMalloc (&lpMalloc); 
if (rc != NOERROR) 

return rc; 


// Ask the shell for the specified folder's pidl. 
rc = SHGetSpecialFolderLocation (hWnd, nFolderID, &pidl); 
if (rc == NOERROR) { 
// Translate the pid] to a directory name. 
SHGetPathFromIDList (pidl, IpDir); 


(continued) 
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// Free the idlist. 
IMalloc_Free(1pMalloc,pidl); 


J 


// Free shell's IMalloc interface. 
IMalloc_Release(1pMalloc); 
return rc; 


This routine calls SHGetMalloc to receive a pointer to the shell’s /Malloc inter- 
face. You then make calls to SHGetSpecialFolderLocation and SHGetPathFromIDList 
to get the folder and translate it into a directory name. Next you call the Free method 
of IMalloc using a macro defined for C-compiled programs. The methods of most COM 
interfaces have macros defined for C-compiled programs if your application isn’t 
written in C++. Finally you call the Release method of IMalloc to free the interface. 

As I mentioned earlier, the Palm-size PC doesn’t formally implement pidls. In- 
stead, SHGetSpecialFolderLocation returns a constant, typed as a pidl, that can then 
be passed to SHGetPathFromIDList to get a directory name. Had the developers also 
implemented a dummy JMalloc interface for the shell, the process for getting the lo- 
cation of a special folder would be identical. Instead, the current version of the Palm- 
size PC shell doesn’t implement an [Malloc interface. Although you could simply 
remove any references to the [Malloc interface, a better solution would be something 
like the following routine: 


INT MyGetSpecialDirectory (HWND hWnd, INT nFolderID, 
LPTSTR IpDir) { 
int rc; 
LPITEMIDLIST pidl; 
BOOL fUseIMalloc = TRUE; 
LPMALLOC 1lpMalloc = NULL; 


// Attempt to get the Shell Malloc interface. 
rc = SHGetMalloc (&1pMalloc); 
if (rc == E_NOTIMPL) 
fUseIMalloc = FALSE; 
else if (rc != NOERROR) 
return rc; 


rc = SHGetSpecialFolderLocation (hWnd, nFolderID, &pidl); 
if (rc == NOERROR) { 
// Translate the idlist to a directory name. 
SHGetPathFromIDList (pidl, IpDir); 
// Free the idlist. 
if (fUseIMalloc) 
IMalloc_Free(]pMalloc,pidl); 
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// Free shell's IMalloc interface. 
if (fUseIMalloc) 

IMalloc_Release(1IpMalloc); 
return rc; 


Shortcuts 


Shortcuts are small files that, when opened, launch an application or open a docu- 
ment in another folder. The idea behind shortcuts is that you could have an applica- 
tion located in one directory but you might want to be able to launch it from other 
directories. Since the shell uses the contents of special directories to define what is in 
the Start menu and on the desktop, placing a shortcut in one of those special direc- 
tories allows an application to appear in the Start menu or on the desktop. 

While the concept of shortcuts was taken from Windows 95, the method of cre- 
ating them was not. Instead of using a COM interface, as is done under Windows 95, 
you create a shortcut in Windows CE using the following function: 


BOOL SHCreateShortcut (LPTSTR szShortcut, LPTSTR szTarget); 


The first parameter specifies the name and location of the shortcut. This name should 
be a fully qualified filename with an extension of LNK. The second parameter is the 
fully qualified filename of the application you want to start or the file you want to 
open. The function returns TRUE if successful. 

You can determine the contents of a shortcut by calling this function: 


BOOL SHGetShortcutTarget (LPTSTR szShortcut, LPTSTR szTarget, 
int cbMax); 


The first parameter is the filename of the shortcut. The remaining two parameters are 
the buffer that receives the target filename of the shortcut and the size of that buffer. 


Configuring the Start Menu 


Shortcuts come into their own when you’re customizing the Start menu. When the 
Start button is clicked, the taskbar looks in its special folder and creates a menu item 
for each item in the folder. Subfolders contained in the special folder become submenus 
on the Start menu. 

The Start menu of the H/PC is limited in that you can’t customize the Start menu 
itself. You can, however, modify the Programs submenu and the submenus it con- 
tains. To add an item to the Programs submenu of the H/PC Start menu, you place a 
shortcut in the folder returned after you called SHGetSpecialFolderLocation with the 
folder constant CSIDL_PROGRAMS. For example, look at the short code fragment 
on the next page; it lists the Calc program in the Programs submenu of the Start 
directory on an H/PC. 
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INT rc; 
TCHAR szDir[MAX_PATH]; 


rc = MyGetSpecialDirectory (hWnd, CSIDL_PROGRAMS, szDir); 
if (rc == NOERROR) { 

Istrcat (szDir, TEXT ("\\Calc.1nk")); 

SHCreateShortcut (szDir, TEXT ("\\windows\\calc.exe")); 


This fragment uses the routine MyGetSpecialDirectory, which I listed earlier in 
the chapter, to return the folder used by the Programs submenu. Once that’s found, 
all that is required is to append the necessary LNK extension to the name of the link 
and call SHCreateShoricut specifying the location of CALC.EXE. 

The Start menu of the Palm-size PC is more flexible than the H/PC’s because 
you can add items directly to the Start menu itself.’ To accomplish this, add shortcuts 
to the folder returned with SHGetSpecialFolderLocation and the constant CSIDL_ 
STARTMENU. From that folder, you can use the standard FindFirstFile and FileNextFile 
functions to determine the structure of the Start menu. 


Recent Documents List 


TH 
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A feature of the Start menu since it was introduced in Windows 95 is the Documents 
submenu. This menu lists the last 10 documents that were opened by applications in 
the system. This list is a convenient place in which users can reopen recently used 
files. The system doesn’t keep track of the last-opened documents. Instead, an appli- 
cation must tell Windows that it has opened a document. Windows then prunes the 
least recently opened document on the menu and adds the new one. 

Under Windows CE, the function that an application calls to add a document to 
the recently used list is 


void SHAddToRecentDocs (UINT uFlags, LPCVOID pv); 


The first parameter can be set to one of two flags, SHARD_PATH or SHARD_PIDL. If 
uFlags is set to SHARD_PATH, the second parameter points to the fully qualified path 
of the document file. If SHARD_PIDL is specified in uFlags, the second parameter 
points to a pointer to an ID list. If the second parameter is 0, all items in the recently 
used document menu are deleted. 


E TASKBAR 


The taskbar interface under Windows CE is almost identical to the taskbar interface 
under Windows 95 and Windows NT 4.0. I’ve already talked about how you can 
configure the items in the Start menu. The taskbar also supports annunciators, those 
tiny icons on the far right of the taskbar. The taskbar icons are programmed by the 
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identical methods used in Windows 95. The only limitation under the current Win- 
dows CE shell is that it doesn’t support tool tips on the taskbar icons. 
Programs can add, change, and delete taskbar icons using this function: 


BOOL Shell_NotifyIcon (DWORD dwMessage, PNOTIFYICONDATA pnid); 


The first parameter, dwMessage, indicates the task to accomplish by calling the func- 
tion. This parameter can be one of the following three values: 


MM MM_ADD Adds an annunciator to the taskbar 
M NIM_DELETE Deletes an annunciator from the taskbar 
M NIM_MODIFY Modifies an existing annunciator on the taskbar 


The other parameter points to a NOTIFYICONDATA structure, which is de- 
fined as 


typedef struct _NOTIFYICONDATA { 
DWORD cbSize; 
HWND hWnd; 
UINT ulID; 
UINT uFlags; 
UINT uCallbackMessage; 
HICON hIcon; 
WCHAR szTip[64]; 
} NOTIFYICONDATA; 


The first field, cbSize, must be filled with the size of the structure before a call is made 
to Shell_NotifyIcon. The hWnd field should be set to the window handle that owns 
the icon. This window receives messages notifying the window that the user has 
tapped, double-tapped, or moved her pen on the icon. The wJD field identifies the 
icon being added, deleted, or modified. This practice allows an application to have 
more than one icon on the taskbar. The uFlags field should contain flags that identify 
which of the remaining fields in the structure contain valid data. 

When you’re adding an icon, the uCallbackMessage field should be set to a 
message identifier that can be used by the taskbar when notifying the window of user 
actions on the icon. This value is usually based on WM_USER so that the message 
value won't conflict with other messages the window receives. The taskbar looks at 
this field only if uFlags contains the NIF_MESSAGE flag. 

The hicon field should be loaded with the handle to the 16-by-16-pixel icon to 
be displayed on the taskbar. You should use LoadImage to load the icon because 
LoadIcon doesn’t return a small format icon. The taskbar looks at this field only if 
the NIF_ICON flag is set in wFlags. Finally, the szTip field would contain the tool- 
tip text for the icon on other Windows systems but is ignored by the current Windows 
CE shells. 
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Managing a taskbar icon involves handling the notification messages the taskbar 
sends and acting appropriately. The messages are sent with the message identifier 
you defined in the call to Shell_NotifyIcon. The wParam parameter of the message 
contains the ID value of the taskbar icon that the message references. The /Param 
parameter contains a code indicating the reason for the message. These values are 
actually the message codes for various mouse events. For example, if the user taps 
on your taskbar icon, the /Param value in the notification message will be WM_ 
LBUTTONDOWN, followed by another message containing WM_LBUTTONUP. 


The TBicons Example Program 
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The TBIcons program demonstrates adding and deleting taskbar annunciator icons. 
Figure 12-1 shows the TBIcons window. The buttons at the bottom of the window 
allow you to add and delete icons from the taskbar. The list box that takes up most of 
the window displays the callback messages as the taskbar sends them. In the taskbar, 
you can see two icons that TBIcons has added. The list box contains a list of mes- 
sages that have been sent by the taskbar back to the TBIcons window. 


aicon 2 WM_LBUTTONDOWN 
aicon 2 WM_LBUTTONDBLCLK 
icon 2 WM_MOUSEMOVE 


dicon 2 WM_MOUSEMOVE 
dicon 2 WM_MOUSEMOVE 
icon 2 WM_LBUTTONUP 


Figure 12-1. 7he Windows CE desktop with a TBIcons window. 


The source code for TBIcons is shown in Figure 12-2. The program uses a dia- 
log box as its main window. The routines that add and delete taskbar icons are 
DoMainCommandAddlIcon and DoMainCommandDellcon. Both these routines sim- 
ply fill in a NOTIFYICONDATA structure and call Shell_NotifyIcon. The routine that 
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handles the notification messages is DoTaskBarNotifyMain. This routine is called when 
the window receives the user-defined message MYMSG_TASKBARNOTIFY, which is 
defined in TBIcons.h as WM_USER+100. Remember that dialog boxes use some of 
the WM_USER message constants, so it’s a good practice not to use the first hundred 
values above WM_USER to avoid any conflicts. 


Figure 12-2. 7Bicons source code. (continued) 
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THE OUT OF MEMORY DIALOG Box 


Because Windows CE applications are almost always running in a limited memory 
environment, it seems likely that they’ll need an Out Of Memory dialog box. The stan- 
dard Windows CE shells give you just such a dialog box as a system service. Figure 12-3 
on the following page shows this dialog box on a Casio E-10 Palm-size PC. 

The advantage of using the system-provided Out Of Memory dialog box is that 
you don’t have to create one yourself in what, by definition, is already a low-memory 
condition. The dialog box provided by the system is also correctly configured for the 
proper screen size and local language. To display an Out Of Memory dialog box, you 
call this function: 


int SHShowOutOfMemory (HWND hwndOwner, UINT grfFlags); 
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Slot. 1ag00000 


/Out 


There is not enough 
memory, Please exit some 
running programs and try 
again. 


The two parameters are the owner window and gr/Flags, which must be set to 0. In 
the latest versions of Windows CE, this function has been moved from the shell so 
that it’s available to embedded systems designed with the Embedded Toolkit (ETK). 


NOTIFICATIONS 


One area in which Windows CE exceeds the Windows 98 and Windows NT API is 
the notification interface. Windows CE applications can register to be launched at a 
predetermined time or when any of a set of system events occur. Applications can 
also register a user notification. In a user notification, the system notifies the user at 
a specific time without the application itself being launched at that time. 

In Windows CE 2.1, the notification interface was moved from the shell to the 
base system. The advantage of this change is that this interface is now available for 
embedded systems. 


User Notifications 
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A Windows CE application can schedule the user to be notified at a given time using 
the CeSetUserNotification function. When the time of the notification occurs, the sys- 
tem alerts the user by displaying a dialog box, playing a wave file, or flashing 
an external LED. Windows CE also displays the icon of the application that set the 
notification on the taskbar. The user has the option of acknowledging the notifica- 
tion either by clicking OK on the notification dialog box, pressing the Notify but- 
ton on the system case, if one is present, or tapping on the application’s taskbar 
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annunciator icon, which launches the application that registered the notification. 
After a user notification has been set, you can modify it by making another call to 
CeSetUserNotification. 


Setting a user notification 
CeSetUserNotification is prototyped as 


HANDLE CeSetUserNotification (HANDLE hNotification, 
TCHAR *pwszAppName, SYSTEMTIME *1IpTime, 
PCE_USER_NOTIFICATION 1pUserNotification); 


The bNotification parameter is set to 0 to create a new notification. To modify a no- 
tification already registered, you should set bNotification to the handle of the user 
notification that you want to modify. The pswzAppName parameter specifies the name 
of the owning application. If this application has a small icon (16-by-16-pixel) image 
in its primary icon, that icon will be displayed as the taskbar annunciator icon when 
the notification occurs. The /pTime parameter is a pointer to a SYSTEMTIME struc- 
ture that specifies the time for the notification to occur. The /pUserNotification pa- 
rameter points to a CE_LUSER_NOTIFICATION structure that describes how the user 
is to be notified. This structure is defined as 


typedef struct UserNotificationType { 
DWORD ActionFlags; 
TCHAR *pwszDialogTitle; 
TCHAR *pwszDialogText; 
TCHAR *pwszSound; 
DWORD nMaxSound; 
DWORD dwReserved; 
} CE_USER_NOTIFICATION; 


The ActionFlags field of this structure contains a set of flags that define how 
the user is notified. The flags can be any combination of the following: 
M PUN_IED Flash the external LED. 
M jPUN_VIBRATE Vibrate the device. 
M PUN_DIALOG Display a dialog box. 
M PUN_SOUND Play a wave file. 
Mm PUN_REPEAT Repeat the wave file for 10 to 15 seconds. 

The fact that these flags are defined doesn’t mean that all systems implement 
all these actions. Most Windows CE devices can’t vibrate and a few don’t even have 
an external LED. There isn’t a defined method for determining the notification capa- 


bilities of a device, but as I’ll presently show you, the system provides a dialog box 
that’s customized by the OEM for the capabilities of each device. 
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The remainder of the fields in the structure depend on the flags set in the 
ActionFlags field. If the PUN_DIALOG flag is set, the pwszDialogTitle and pwsz-— 
DialogText specify the title and text of the dialog that’s displayed. The pwszSound 
field is loaded with the filename of a wave file to play if the PUN_SOUND flag is set. 
The nMaxSound field defines the size of the pwsSound field. 


Configuring a user notification 

To give you a consistent user interface for choosing the method of notification, 
Windows CE provides a dialog box to query the user how he wants to be notified. 
To display the user configuration dialog box, you call this function: 


BOOL CeGetUserNotificationPreferences (HWND hWndParent, 
PCE_USER_NOTIFICATION IpNotification) ; 


This function takes two parameters—the window handle of the parent window for 
the dialog box and a pointer to a CE_LUSER_NOTIFICATION structure. You can ini- 
tialize the CE_LUSER_NOTIFICATION structure with default settings for the dialog 
before CeGetUserNotificationPreferences is called. When the function returns, this 
structure is filled with the changes the user made. CeGetUserNotificationPreferences 
returns TRUE if the user clicked on the OK button to accept the changes and FALSE 
if an error occurred or the user canceled the dialog box. 

This function gives you a convenient method for configuring user notifications. 
The dialog box lets you have check boxes for playing a sound, displaying another 
dialog box, and flashing the LED. It also contains a combo box that lists the available 
wave files that the user can choose from if he wants sound. The dialog box doesn’t - 
have fields to allow the user to specify the text or title of the dialog box if one is to be 
displayed. That text must be provided by the application. 


Acknowledging a user notification 
A user notification can be cleared by the application before it times out by calling 


BOOL CeClearUserNotification (HANDLE hNotification); 


Once a user notification has occurred, it must be acknowledged by the user. The user 
can tap the OK button on the notification dialog box or press the notification button 
on the H/PC or Palm-size PC case. A third alternative is for the user to tap on the 
taskbar icon of the program that registered the notification. This icon is displayed by 
the system when the notification is made. In this case, Windows CE launches the 


_ application. 
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If the user taps on the taskbar icon, the notification isn’t automatically acknowl- 
edged. Instead, an application should programmatically acknowledge the notifica- 
tion by calling this function: 


BOOL CeHandleAppNotifications (TCHAR *pwszAppName) ; 
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The one parameter is the name of the application that was launched due to the taskbar 
icon tap. Calling this function removes the dialog box, stops the sound, turns off the 
flashing LED, and removes the application’s annunciator icon from the taskbar. 

When the system starts an application due to a notification, it passes a command 
line argument to indicate why the application was started. For a user notification, this 
argument is the command line string AppRunToHandleNotification followed by a space, 
and the handle of the notification. Instead of using the literal string for comparison, 
notify.h, which is the include file that contains the notification API, includes defines for 
the command line strings. The constant for AppRunToHandleNotification is APP_RUN_ 
TO_HANDLE_NOTIFICATION. 

As a general rule, an application started by a notification should first check to 
see whether another instance of the application is running. If so, the application should 
communicate to the first instance that the notification occurred and terminate. This 
saves memory because only one instance of the application is running. The code frag- 
ment below shows how this can be easily accomplished. 


INT 7; 

HWND hWnd; 

HANDLE hNotify; 
TCHAR szText[128]; 


if (*1lpCmdLine) { 
pPtr = |lpCmdLine; 
// Parse the first word of the command line. 
for (i = @; i < dim(szText) && *IlpCmdLine > TEXT (' '); i++) 
szTextLi] = *pPtr++; 
szTextLi] = TEXT ('\Q@'); 


// Check to see if app started due to notification. 

if (lstrcemp (szText, APP_RUN_TO_HANDLE_NOTIFICATION) == @) { 
// Acknowledge the notification 
GetModuleFileName (hInst, szText, sizeof (szText)); 
CeHandleAppNotifications (szText); 


// Get handle off the command line. 
hNotify = (HANDLE)_wtol (pPtr); 


// Look to see if another instance of the app is running. 
hWnd = FindWindow (NULL, szAppName) ; 
if (hWnd) { 
SendMessage (hWnd, MYMSG_TELLNOTIFY, @, (LPARAM)hNotify); 
// This app should terminate here. 
// return Q; 
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This code first looks to see whether a command line parameter exists and if so, 
whether the first word is the keyword indicating that the application was launched 
by the system in response to a user notification. If so, the notification is acknowl- 
edged and the application looks for an instance of the application already running, 
using FindWindow. If found, the routine sends an application-defined message to 
the main window of the first instance and terminates. Otherwise, the application can 
take actions necessary to respond to the user’s tap of the program icon on the taskbar. 


Timer Event Notifications 


To run an application at a given time without user intervention, use a timer event 
notification. The function that creates a timer event notification is this one: 


BOOL CeRunAppAtTime (TCHAR *pwszAppName, SYSTEMTIME *1]pTime) ; 


The two parameters are the name of the application to launch and a pointer to 
a SYSTEMTIME structure to set the time to launch the application. Only one timer 
event notification can be set for any one application. Calling CeRunAppAtTime a sec- 
ond time with a new time simply replaces the first notification with the second. A 
timer notification can be cleared by passing a NULL pointer in the JpTime parameter. 

When the timer notification is activated, the system powers on, if currently off, 
and launches the application with a command line parameter of APP_RUN_AT_TIME. 
As with the user notification, the application should check to see whether another in- 
stance of the application is running and pass the notification on if one is running. Also, 
an application should be careful about creating a window and taking control of the 
machine during a timer event. The user might object to having his game of solitaire 
interrupted by another application popping up because of a timer notification. 


System Event Notifications 
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Other times, you might want an application to be automatically started. Windows CE 
supports a third type of notification, known as a system event notification. This noti- 
fication starts an application when one of a set of system events occurs, such as after 
the system has completed synchronizing with its companion PC. To set a system event 
notification use this function: 


BOOL CeRunAppAtEvent (TCHAR *pwszAppName, LONG 1WhichEvent); 


As with the timer event notification, the first parameter is the name of the application 
to launch. The second parameter is a constant indicating which event to monitor. The 
flags are the following: 


M NOTIFICATION_EVENT_NONE Clear event notifications. 
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M £ NOTIFICATION_EVENT_SYNC_END Notify when sync complete. 


id NOTIFICATION_EVENT_DEVICE_CHANGE Notify when a PCMCIA de- 
vice is added or removed. 


M £ NOTIFICATION_EVENT_RS232_DETECTED Notify when an RS232 con- 
nection is detected. 


M £éNOTIFICATION_EVENT_TIME_CHANGE Notify when the system time is 
changed. 


M £ NOTIFICATION_EVENT_RESTORE_END Notify when a device restore is 
complete. 


For each of these events, the application is launched with a specific command 
line parameter indicating why the application was launched. In the case of a device 
change notification, the NOTIFICATION_EVENT_DEVICE_CHANGE command line 
string is followed by either /ADD or /REMOVE and the name of the device being added 
or removed. For example, if the user inserts a modem card, the command line for the 
notification would look like this: 


AppRunDeviceChange /ADD COM3: 


A number of additional system events are defined in notify.h but at this point, none 
are currently supported. 

Once an application has registered for a system event notification, Windows CE 
will start the application again if the event that caused the notification is repeated. To 
stop being notified, an application must call CeRunAppAtEvent and pass its name and 
NOTIFICATION_EVENT_NONE in the /WhichEvent parameter. 


The MyNotify Example Program 


The following program, MyNotify, demonstrates each of the notification functions that 
allow you to set user notifications, system notifications, and timer notifications. The 
program presents a simple dialog box that has four buttons. The first two buttons 
allow you to configure and set a user notification. The second two buttons let you 
set system and timer notifications. The gap above the buttons is filled with the com- 
mand line, if any, that was passed when the application started. It’s also used to dis- 
play a message when another instance of MyNotify is started due to a user notification. 
Figure 12-4 on the following page shows two MyNotify windows. The one in the fore- 
ground was launched because of a user notification, while the one in the background 
displays a message, indicating it was sent a message from the other instance of the 
application. 
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Figure 12-4. The MyNotify window. 


The source code for MyNotify is shown in Figure 12-5. The notification code is 
confined to the button handler routines. The code is fairly simple: for each type of 
notification, the appropriate Windows CE function is called. When asked to config- 
ure a user notification, the application calls CeGetUserNotificationPreferences. The 
program gives you one additional dialog box with which to configure the system 
notifications. 


Figure 12-5. 7he MyNotify program. 
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(continued) 
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Figure 12-5. continued 
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(continued) 
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When MyNotify is started, it examines the command line to determine whether 
it was started by a user notification. If so, the program attempts to find another in- 
stance of the application already running. If the program finds one, a message is sent 
to the first instance, informing it of the user notification. Because this is an example 
program, the second instance doesn’t terminate itself as it would were it a com- 
mercial application. 


CONSOLE APPLICATIONS 
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A console driver was added to Windows CE in version 2.1. Windows CE doesn’t sup- 
port the character mode API supported by Windows NT. Instead, a Windows CE 
console application just uses the standard C library I/O functions, such as printfand 
getc, to read and write characters from the command line. Another major difference 
between command line applications on Windows CE and on other versions of Win- 
dows is that they use the standard WinMain entry point instead of the standard C 
entry point of main. 

Below is a Windows CE console application that runs under Windows CE 2.1. 
Aside from the difference of the entry point, a Windows CE console application looks 
like any other standard C command line application. 


// 

// HelloCon - A simple console application 

// 

#Finclude <windows.h> // For all that Windows stuff 


// Program entry point 
int WINAPI WinMain (HINSTANCE hInstance, HINSTANCE hPrevinstance, 
LPWSTR IpCmdLine, int nCmdShow) { 


// You don't use Unicode for the stdio functions... 
printf ("Hello World\n"); 


//...but you can with the ‘w' versions. 
wprintf (TEXT ("Hello World\n")); 
return Q; 


Windows CE console applications have access to the Win32 API. In fact, a con- 
sole application can create windows, enter a message loop, and operate as if it were 
a standard Windows application. The difference is that the first time you call one of 
the stdio C library functions, such as printf, a console window is created and the re- 
sult of that function will be seen in that window. 

You implement consoles under Windows CE using a console driver with the 
appropriate device name of CON. Up to 10 console windows can be opened at any 
one time. The limit comes from the CONO through CON9 naming convention used 
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Figure 12-6. The results of a CEFind search for TrueType font files. 
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(continued) 
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Figure 12-7. continued 
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very differently. These differences show up the most in places, such as the Explorer, 
where almost all of the COM interfaces are unique and private, and in console appli- 
cations, where the implementation is limited to supporting a subset of standard C library 
calls and nothing else. 

The next chapter covers the tablet mode shell components. These shell com- 
ponents were first introduced for the Palm-size PC. These components include the 


SIP (the supplementary input panel), and dedicated hot keys on the system. Let’s 
take a look. 
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Shell Programming 
—Part 2 


A Windows CE programmer needs to understand at least three shells when program- 

- ming a Windows CE device. The Handheld PC and Handheld PC Pro devices, each 
equipped with a keyboard and a landscape-oriented screen, use an Explorer-type shell 
that looks similar to the shell used by Windows 95 and Windows NT 4. The Palm- 
size PC and other Windows CE keyboardless devices, which come equipped with a 
portrait-oriented screen, use a completely different shell, one that doesn’t expose the 
file system to the user. Each of these devices has an Active Desktop that displays in- 
formation from various applications directly on the desktop. The third shell a Win- 
dows CE programmer needs to know is the one not written. This is the custom shell, 
written by the OEM designing an embedded device. 

This chapter covers components that most directly relate to the Palm-size PC 
shell, although the technologies presented in this chapter aren’t restricted to use in 
the Palm-size PC. The primary difference between the Palm-size PC and other Win- 
dows CE devices is the Palm-size PC’s lack of a full hardware keyboard. In its place, 
is the Supplementary Input Panel, or SIP, which gives the user a way to register key- 
strokes directly on the screen. However, as with many Windows CE technologies, the 
SIP has now been generalized in Windows CE 2.1 for use on other platforms. 

Pll also cover how to handle the hardware buttons that are on many Palm-size 
PCs. These buttons can be used two ways—to launch an application or to provide 
additional keys to an application while it’s running. While the navigation buttons are 
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specific to the Palm-size PC, the application launch buttons are also available on some 
Handheld PC and Handheld PC Pro systems as well as other Windows CE-based 
systems. 


THE SUPPLEMENTARY INPUT PANEL 


The SIP gives the user access to a keyboard’s capacities on devices that don’t have a 
keyboard or at times when the keyboard of a device isn’t available to the user. Having 
a SIP on a Windows CE system affects the application in a couple of ways. First the 
screen real estate used by the SIP isn’t available to the application. Second since the 
SIP can be displayed and hidden interactively by the user, the amount of the screen 
that’s available to the application can change while the application is running. What 
doesn’t change is the way an application deals with keyboard input. Characters entered 
by means of a SIP appear to an application in the same message-based way that keys 
appear if they’re pressed on a hardware keyboard. That is, the same series of WM_ 
KEYDOWN, WM_CHAR, and WM_KEYUP messages are generated by the system in 
response to a key being entered through a SIP. 

A SIP can use a number of different input methods or IMs. These input meth- 
ods are installable components and provide the user interface to the SIP. Two such 
input methods are the keyboard IM and the Jot Character recognizer IM, which are 
provided on the Palm-size PC. 


Working with a SIP 


The functions available to Windows CE applications for interaction with the SIP have 
changed since they were introduced with the Palm-size PC. So while Windows CE 2.1 
adds a newer and more general set of functions, I’m going to present the Palm-size 
PC functions first, because most applications dealing with the SIP run, at this point, 
on the Palm-size PC. At the end of this section, I’ll describe the different functions 
provided by Windows CE 2.1 for use with the SIP. 

The primary function an application uses when dealing with the SIP on a Palm- 
size PC is SHSipInfo. This omnibus function allows an application to receive infor- 
mation about the current SIP settings (such as its location), set those settings, query 
the current default SIP, and even change the default SIP. The function is prototyped as 


BOOL SHSipInfo (UINT uiAction, UINT uiParam, PVOID pvParam, 
UINT fWinIni); 


The first parameter to SHSipInfo, uiAction, should be set with a flag that specifies the 
action you want to perform with the function. The allowable flags are these: 
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M SPI_SETSIPINFO Sets the SIP configuration including its location and its 
visibility 
| SPI_GETSIPINFO Queries the SIP configuration 


SPI_SETCURRENTIM Sets the current default input method 
M SPI_GETCURRENTIM Queries the current default input method 


Because the behavior of SHSipInfo is completely different for each of the flags, 
I’ll describe the function as if it were four different function calls. For each of the flags 
though, the second and fourth parameters, uiParam and fWinIni, must be set to 0. 


Querying the state of the SIP 
To query the current state of the SIP, you would call SHSipInfo with the SPI_GET- 
SIPINFO flag in the uiAction parameter. In this case, the function looks like this: 


BOOL SHSipInfo (SPI_LGETSIPINFO, @, SIPINFO *psi, @); 
The third parameter must point to a SIPINFO structure, which is defined as 


typedef struct { 
DWORD cbSize; 
DWORD fdwFlags; 
RECT rcVisibleDesktop; 
RECT rcSipRect; 
DWORD dwImDataSize; 
VOID *pvImData; 

} SIPINFO; 


The structure’s first field, cbSize, must be set to the size of the SIPINFO struc- 
ture before a call is made to SHSipInfo. The second field in SIPINFO, fdwFlags, can 
contain a combination of the following flags: 


Mm SIPF_ON When set, the SIP is visible. 


M SIPF_DOCKED When set, the SIP is docked to its default location on the 
screen. 


M SIPF_LOCKED When set, the visibility state of the SIP can’t be changed 
by the user. 


The next two fields of SIPINFO provide information on the location of the SIP. 
The field rcVisibleDesktop is filled with the screen dimensions of the visible area of 
the desktop. If the SIP is docked, this area is the rectangle above the SIP. If the SIP 
is undocked, this rectangle contains the full desktop area minus the taskbar, if it’s 
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showing. This field is ignored when you set the SIP configuration. Some SIPs might 
have a docked state that doesn’t run from edge to edge of the screen. In this case, the 
rectangle describes the largest rectangular area of the screen that isn’t obscured by 
the SIP. | 

The rcSipRect field contains the location and size of the SIP. If the SIP is docked, 
the rectangle is usually the area of the screen not included by rcVisibleDesktop. But if 
the SIP is undocked, rcSipRect contains the size and position of the SIP while 
rcVisibleDesktop contains the entire desktop not obscured by the taskbar, including 
the area under the SIP. Figure 13-1 shows the relationship between rcVisibleDesktop 
and rcSipRect. 


<p  t 


rcVisibleDesktop 


rcVisibleDesktop 


rcSipRect 
SIP 


Docked SIP Undocked SIP 
Figure 13-1. The relationship between rcVisibleDesktop and rcSipRect in the 
SIPINFO structure. 


The final two fields of SIPINFO allow you to query information specific to the 
current input method. The format of this information is defined by the input method. 
To query this information, the pulmData field should be set to point to a buffer to 
receive the information and dwIlmDataSize should be set to the size of the buffer. It 
is up to the application to know which input methods provide what specific data. 
For most input methods, these two fields should be set to 0 to indicate that no IM- 
specific data is being queried. 


Setting the SIP configuration 
To set the configuration of the current SIP, you call SHSipInfo with the SPI_SETSIPINFO 
flag, as in 


BOOL SHSipInfo (SPI_SETSIPINFO, @, SIPINFO *psi, @); 
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The parameters are the same as when you call to query the SIP configuration with 
the third parameter pointing to a SIPINFO structure. As a general rule, you shouldn’t 
fill in the SIPINFO fields from scratch. Instead, you should call SHSip/nfo to fill in the 
SIPINFO structure, modify the fields necessary to make your change, and then call 
SHSipInfo again to make the changes. That said, you really can’t change much with 
the present version of the Palm-size PC shell. Currently, an application can’t undock 
a SIP, move the SIP, or even dock an undocked SIP. The only state that an application 
can change is to show or hide the SIP by toggling the SIPF_ON flag in the fdwFlags 
field of the SIPINFO structure. 


Changing the default input method 

You can use SHSipInfo to query and to change the current SIP. To query the current 
SIP, you call SHSipInfo with the SPI.GETCURRENTIM flag in the uiAction parameter 
as in 


BOOL SHSipInfo (SPI_SETSIPINFO, @, CLSID *pclsid, @); 


In this case, the third parameter points to a CLSID variable that receives the CLSID of 
the current input method. 

To set the current input method, call SHSipInfo with the uiAction parameter set 
to SPI_SETCURRENTIM, as in 


BOOL SHSipInfo (SPI_SETSIPINFO, 0, CLSID *pclsid, Q@); 


Here again, the third parameter of SHSipInfo is a pointer to a CLSID value. In this 
case, the value must contain a CLSID of a valid input method. 


Enumerating the installed input methods 

The Palm-size PC has no function that enumerates the input methods that are installed 
on a system. So applications must iterate through the registry to find the input method 
DLLs. Fortunately, this isn’t an onerous task because input methods are COM objects, 
and an input method is required to have a special key named JsS/PInputMethod with 
a default value of 1 in its COM registration key. So, to enumerate the installed input. 
methods, all you have to do is enumerate the CLSID keys under [HKEY_CLASSES_ | 
ROOTI\CLSID. In each key that you open, look for the subkey JsS7PInputMethod. If 
you find it, the entry is the CLSID of an input method and the default value of the 
CLSID key is the name of the input method. 

The routine that follows enumerates the installed input methods. The routine 
fills a buffer with a list of strings. For each input method found, the routine returns 
two strings, the CLSID of the input method and the input method’s friendly name. 
The list is terminated with a null character. 
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// EnumerateInputMethods - Produces a list of installed input methods 
// and their CLSIDs 
// 
int EnumerateInputMethods (LPTSTR pOut, int sMax) { 
INT i = @, rc, nCnt = Q; 
HKEY hKey, hSubKey, hKey2; 
DWORD dwType, dwSize; 


// Open CLSID key. 
if (RegOpenKeyEx (HKEY_CLASSES_ROOT, TEXT ("CLSID"), @, 
Q@, &hKey) != ERROR_SUCCESS) 

return Q; 
sMax -= 2; // Make room for terminating zero. 
while (sMax > @) { 

// Enumerate active driver list. 

dwSize = sMax; 

if (RegEnumKeyEx (hKey, i++, pOut, &dwSize, NULL, NULL, 

NULL, NULL) != ERROR_SUCCESS) 
break; 


// Open object ID key for object. 
rc = RegOpenKeyEx (hKey, pOut, 0, 0, &hSubKey); 
if (rc != ERROR_SUCCESS) 

continue; 


// See if IsSIPMethod key present indicating an IM object. 
rc = RegOpenKkKeyEx (hSubKey, TEXT ("IsSIPInputMethod"), @, Q, 
&hKey2); 


if (rc == ERROR_SUCCESS) { 
RegCloseKey (hKey2); 
// Move output pointer beyond CLSID. 
sMax -= (lstrlen (pOut) + 1) * sizeof (TCHAR); 
if (sMax > @) | 
pOut += Istrlen (pOut) + 1; 
else 
break; 
// Get name of IM. 
dwSize = sMax; 
re = RegQueryValueEx (hSubKey, @, 0, &dwType, 
(PBYTE)pOut, &dwSize); 
RegCloseKey (hSubKey); 
if (rc != ERROR_SUCCESS) { 
*pOut = TEXT ('\@'); 
RegCloseKey (hSubKey); 
RegCloseKey (hKey); 
return -1; 
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// Move output pointer beyond current name. 
SMax -= (int)dwSize; 
if (sMax > Q) 
pOut += Istrlen (pOut) + 1; 
nCnt++; 
j 
RegCloseKey (hSubKey); 


RegCloseKey (hKey); 
// Add terminating zero. 
if (!rc) 


*pOut = TEXT ('\@"); 


return nCnt; 


Reacting to SIP Changes 


When the user or an application displays or hides the SIP, the Palm-size PC shell sends 
a WM_SETTINGCHANGE message to all top-level windows. To indicate that the 
message was sent in response to the state of the SIP changing, the wParam value is 
set to the constant SPI_SETSIPINFO. You can then call SHSipinfo to determine the 
new state of the SIP. Note that while this message is sent to all top-level windows, 
only the foreground window should make any changes to the SIP. A window not in 
the foreground can save the indication that the SIP state has changed and respond 
when that window is brought to the foreground. 

When the user changes the input method of the SIP, a WM_SETTINGCHANGE 
message is sent to all top-level windows. In this case, the wParam value is set to the 
constant SPISETCURRENTIM. 

When a foreground application detects that the SIP has been displayed, it should 
ensure that the SIP doesn’t obscure the location of the input caret or, in the case of a 
dialog box, the control that currently has focus. In most cases, this means scrolling 
the window or reconfiguring the dialog box so that the user can see the control even 
with the SIP displayed. Another option is to always have controls laid out on the top 
two thirds of the Palm-size PC screen because docked SIPs won’t obscure this area. 


Input Panels on Windows CE 2.1 Devices 


One of the goals of Windows CE 2.1 was to take some of the more interesting and 
useful functional units of the different H/PC and Palm-size PC shells and move them 
into the base operating system. This would allow developers of embedded systems, 
who don’t currently have access to those complex shells, to use those functional blocks. 
One of the functional blocks moved is the notification API that I talked about in Chapter 
12. Another functional block is the SIP architecture. When the SIP was moved to the 
operating system from the shell, the API for the SIP was redesigned to be a more general 
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API. Because of this, SIP-aware applications written for Windows CE 2.1 need to use 
a different set of functions than used by their Palm-size PC cousins. 

Note that the SIP API isn’t the same IME API that’s also supported on Win- 
dows CE 2.1. The IME API is a much more general and complex API than the rela- 
tively simple SIP needs. 

The first four functions of the Windows CE 2.1 SIP API correspond directly to 
the four different modes of the Palm-size PC’s SHSipinfo functions. Their prototypes 
are 


BOOL SipGetInfo (SIPINFO *pSIPInfo); 
BOOL SipSetInfo (SIPINFO *pSIPInfo); 
BOOL SipGetCurrentIM (CLSID *pClsid); 
BOOL SipSetCurrentIM (CLSID *pClsid); 


Both SipGetinfo and SipSetInfo use the same SIPINFO structure that I described ear- 
lier in connection to the SHSipInfo function. Likewise, the SipGetCurrentIM and 
SipSetCurrentIM functions use pointers to CLSID values to identify the input methods. 

A new function has been added to simplify the process of showing and hiding 
the SIP. Instead of using SipGetInfo and SipSetInfo to fill in a SIPINFO structure and 
modify the SIPF_ON flag to show or hide the SIP, you can use the SipSbowIM func- 
tion. It’s prototyped as 


BOOL SipShowIM (DWORD dwFlags); 


The only flags that can be specified are SPIF_ON and SPIF_OFF. 

Instead of your having to manually enumerate the input methods by looking 
through the registry, you can use a new function, SipEnumIM. This function is 
prototyped as 


int SipEnumIM (IMENUMPROC pEnumIMProc); 


The only parameter is a pointer to an enumeration function in your application. If 
you pass NULL in the pEnumIMProc parameter, SipEnumIM returns the number of 
input methods installed on the system. The callback function should be prototyped as 


int SipEnumIMProc (IMENUMINFO « pIMInfo); 


Windows CE will call the enumeration function once for each input method 
installed on the system. The function will be called with the parameter pointing to an 
IMENUMINFO structure, which is defined as 


struct _IMENUMINFO { 
TCHAR szName[MAX_PATH] ; 
CLSID Clsid; 

} IMENUMINFO; 
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Here again, the fields are fairly self-explanatory. The szName is the friendly name of 
the IM, while the Clsid field contains the CLSID value for the IM. 

Another function is SipStatus. This function tells the caller whether the SIP com- 
ponent of Windows CE is installed on a system. The function is prototyped as 


DWORD SipStatus(void); 


The function returns SIP_STATUS AVAILABLE if the SIP functions are available or 
SIP_STATUS_UNAVAILABLE if the SIP component isn’t installed. 

The last two functions are provided for SIP maintenance. The Palm-size PC 
doesn’t need these functions because its shell maintains the SIP. For systems whose 
shells don’t have knowledge of a SIP, you’ll have to write an application that main- 
tains the SIP through these functions. A better alternative would be to have your custom 
shell provide the SIP maintenance through these functions. 

On the Palm-size PC, the taskbar maintains the button that displays and hides 
the SIP window. The taskbar maintains a button that displays a bitmap, which repre- 
sents the current input method so that the user knows which input method is the 
default. On other systems, this function must be performed by another application 
or more likely, by a custom shell. To provide this function, the custom shell needs to 
know what bitmap the SIP wants displayed, while also maintaining the default rect- 
angle for the SIP. Windows CE 2.1 gives you two functions for this purpose. 

The SipRegisterNotification function can be called by the application that main- 
tains the SIP. This application will then be notified when the input method changes 
the bitmaps that are used to represent the input method. Only one application, the 
application that manages the SIP, can call SipRegisterNotification to ask to be noti- 
fied when the SIP changes state. That application will then be notified about input 
method changes until the system is rebooted. The function is prototyped as 


BOOL SipRegisterNotification (HWND hWnd); 


The only parameter is the window that will receive the notifications. That window 
will receive WM_IM_INFO messages when an input method initially sets or later 
changes its bitmaps. The wParam for this message contains one of the following flags, 
indicating what’s being changed by the input method. These flags are 

M #IM_POSITION The size or position of the input method has changed. 

mM IM_WIDEIMAGE The input method has selected a new wide image. 


Mm IM_NARROWIMAGE ‘The input method has selected a new narrow 
image. 
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The /Param parameter contains different data, depending on the flag. For 
IM_POSITION, /Param isn’t used. For IM_WIDEIMAGE and IM_NARROWIMAGE, 
lParam contains the handle to the new bitmap to be used. 

The final function is also used by the custom shell or the application maintain- 
ing the SIP. It is 


BOOL SipSetDefaultRect (RECT * pRect); 


This function is called to set the default docked rectangle for the SIP. This allows a 
custom shell to define where the docked position of the SIP is to be on the screen. 
The only parameter is the rectangle that defines the default location. This new loca- 
tion won’t be used until a new input method is selected either by the user or by the 
program. 

You might want to have your SIP-aware applications that need to be cross-com- 
patible with the Palm-size PC shell manually load the function pointers to the differ- 
ent SIP functions. This procedure would allow an application to run both on the 
Palm-size PC as well as on any embedded Windows CE 2.1 or later system. I describe 
how to do this in Chapter 14. 


WRITING AN INPUT METHOD 


Up to this point, ’ve talked only about the application side of dealing with SIPs. You 
can also design your own input method rather easily. An input method is merely a 
COM object that exports an IInputMethod interface and creates an input method 
window in response to requests from the input panel. 


The Components of a SIP 
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A SIP is composed of two main components—the input panel and the input method. 
The input panel is supplied by the system. It creates the input panel window, pro- 
vides the message loop processing for the SIP, and the window procedure for the 
input panel window. The input panel cooperates with the taskbar or other shell pro- 
gram to provide the user with the ability to switch between a number of installed 
input methods. 

The input method is the installable portion of the SIP. It’s responsible for trans- 
lating pen strokes and taps into keyboard input. It’s also responsible for the look and 
feel of the SIP while it’s selected. In almost all cases, the input method creates a win- 
dow that’s a child of the input panel window. Within that child window, the input 
method draws its interface and interprets mouse messages. The input method then 
calls back to the input panel when it wants to generate a key event. | 

Each of these two components implements a COM interface that becomes the 
interface between them. The input method implements an IInputMethod interface, 
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while the input panel implements an 7MCallback interface. In the interaction between 
the input panel and the input method, the input panel drives the interaction. For the 
most part, the input method simply responds to calls made to its ImputMethod meth- 
ods. Calls are made when the input method is loaded, when it’s unloaded, and when 
it's shown or hidden. In response, the input method must draw in its child window, 
interpret the user’s actions, and call methods in the IMCallback interface to send keys 
to the system or to control the input panel’s window. 

Input methods are implemented as COM in-proc servers. Because of this, they 
must conform to the standard COM in-proc server specifications. This means that an 
input method is implemented as a DLL that exports DilGetClassObject and DilCan- 
UnloadNow functions. Input methods must also export DilRegisterServer and DIlI- 
UnregisterServer functions that perform the necessary registry registration and 
unregistration for the server DLL. 


Threading Issues with Input Methods 


Because the input panel and input method components are so tightly interrelated, 
you must follow a few rules when writing an input method. While it’s permissible to 
use multiple threads in an input method, the interaction between the input panel and 
the input method is strictly limited to the input panel’s primary thread. This means 
that the input method should create any windows during calls to methods in the 
IInputMethod interface. This ensures that these windows will use the same message 
loop as the input panel’s window. This, in turn, allows the input panel to directly call 
the input method’s window procedures, as necessary. In addition, that same thread 
should make all calls made back to the WMCallback interface. 

In short, try not to multithread your input method. If you must, create all win- 
dows in your input method using the input panel’s thread. Secondary threads can be 
created, but they can’t call the ZMCallback interface and they shouldn’t create any 
windows. 


The [inputMethed Interface 


The InputMethod interface is the core of an IM. Using the interface’s methods, an IM 
should create any windows, react to any changes in the parent input panel window, 
and provide any cleanup when it’s released. The IInputMethod interface exports the 
following methods in addition to the standard JUnknown methods: 


M 8 IlnputMethod.:Select The user has selected the IM. The IM should cre- 
ate its window. 


| IInputMethod::Deselect The user has selected another IM. The IM should 
destroy its window. 
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IInputMethod::Showing The IM window is about to be displayed. 
IInputMethod::Hiding The IM window is about to be hidden. 


a) 

i) 

M IlmputMethod::Getinfo ‘The system is querying the IM for information. 

— IlnputMethod.:ReceiveSipInfo The system is providing information to the IM. 
a 


IInputMethod::RegisterCallback ‘The system is providing a pointer to the 
IMCallback interface. 


M 8 IlnputMethod::GetImData ‘The IM is queried for IM-specific data. 
M IlInputMethod::SetImData ‘The IM is provided IM-specific data. 


M 8 InputMethod::UserOptionsDig The IM should display an options dialog 
box to support the SIP control panel applet. 


Let’s now look at these methods in detail so that we can understand the pro- 
cessing necessary for each. | 


IinputMethod::Select 
When the user chooses your input method, the DLL that contains your IM is loaded 
and the Select method is called. This method is prototyped as 


HRESULT IInputMethod::Select (HWND hwndSip):; 


The only parameter is the handle to the SIP window that’s the parent of your input 
method’s main window. You should return S_OK to indicate success or E_FAIL if you 
can’t create and initialize your input method successfully. 

When the Select method is called, the IM will have just been loaded into memory 
and you'll need to perform any necessary initialization. This includes registering any 
window classes and creating the input method window. The IM should be created as 
a child of the SIP window because it’s the SIP window that will be shown, hidden, 
and moved in response to user action. You can call GetClientRect with the parent 
window handle to query the necessary size of your input window. 


IinputMethod::Getinfo 

After the input panel has loaded your IM, it calls the Getinfo method. The input panel 
calls this method to query the bitmaps that represent the IM. These bitmaps appear 
in the SIP button on the taskbar. In addition, the IM can provide a set of flags and the 
size and location on the screen where it would like to be displayed. This method is 
prototyped as 


HRESULT IInputMethod::GetInfo (IMINFO *pimi); 


The only parameter is a pointer to an IMINFO structure that the IM must fill out to 
give information back to the SIP. The IMINFO structure is defined as 
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typedef struct { 
DWORD cbSize; 
HANDLE hImageNarrow; 
HANDLE hImageWide; 
int iNarrow; 
int iWide; 
DWORD fdwFlags; 
RECT rcSipRect; 
} IMINFO; 


The first field, cbSize, must be filled with the size of the IMINFO structure. The 
next two fields, bhImageNarrow and hImageWide, should be filled with handles to 
image lists that contain the bitmaps that will appear on the taskbar SIP button. The 
wide image is a 32-by-16-pixel bitmap that’s used when the shell has room to display 
the wide SIP button on the taskbar. When space on the taskbar is constrained, the 
system narrows the SIP button and displays the 16-by-16 bitmap from the Narrow 
image list. The input method must create these image lists and pass the handles in 
this structure. The IM is responsible for destroying the image lists when a user or an 
application unloads it. You can create these image lists in the GetInfo method, as long 
as you design your application to know not to create the image lists twice if GetInfo 
is called more than once. Another strategy is to create the image lists in the Select 
method and store the handles as member variables of the InputMethod object. Then 
when GetInfo is called, you can pass the handles of the already created image lists to 
the input panel. 

The next two fields, iNarrow and iWide, should be set to the index in the im- 
age lists for the bitmap you want the SIP to use. For example, you might have two 
different bitmaps for the SIP button, depending on whether your IM is docked to the 
taskbar or is floating. You can then have an image list with two bitmaps, and you can 
specify the index depending on the state of your IM. 

The fdwFlags field should be set to a combination of the flags, SIPF_ON, SIPF_ 
DOCKED, SIPF_LOCKED, and SIPF_DISABLECOMPLETION, all of which define the 
state of the input panel. The first three flags are the same flags that I described ear- 
lier. When the SIPF_DISABLECOMPLETION flag is set, the auto-completion function 
of the SIP is disabled. 

Finally, the rcSipRect field should be filled with the default rectangle for the input 
method. Unless you have a specific size and location on the screen for your IM, you 
can simply query the client rectangle of the parent SIP window for this rectangle. Note 
that just because you request a size and location of the SIP window doesn’t mean 
that the window will have that rectangle. You should always query the size of the 
parent SIP window when laying out your IM window. 
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IinputMethod::ReceiveSipinfo 

The ReceiveSipInfo method is called by the input panel when the input panel is shown 
and then again when an application moves or changes the state of the input panel. 
The method is prototyped as 


HRESULT IInputMethod::ReceiveSipInfo (SIPINFO *psi); 


The only parameter is a pointer to a SIPINFO structure that I described earlier in this 
chapter. When this method is called, only two of the fields are valid—the fdwFlags 
field and the reSipRect field. The rcSipRect field contains the size and location of the 
input panel window, while the fdwFlags field contains the SIPF_xxx flags previously 
described. In response to the ReceiveSipInfo method call, the IM should save the new 
state flags and rectangle. 


IinputMethod::RegisterCallback 
The input panel calls the RegisterCallback method once, after the input method has 
been selected. The method is prototyped as 


HRESULT IInputMethod::RegisterCallback (IIMCallback *IpIMCallback); 


This method is called to provide a pointer to the MCallback interface. The only action 
the IM must take is to save this pointer so that it can be used to provide feedback to 
the input panel. 


IinputMethod::Showing and [inputMethod::Hiding 

The input panel calls the Showing and Hiding methods just before the IM is shown 
or hidden. Both these methods have no parameters and you should simply return 
S_OK to indicate success. The Showing method is also called when the panel is moved 
or resized. This makes the Showing method a handy place for resizing the IM child 
window to properly fit in the parent input panel window. 


IinputMethod::GetimData and [inputMethod::SetimData 

The GetImData and SetImData methods give you a back door into the IM for appli- 
cations that need to have a special communication path between the application and 
a custom IM. This arrangement allows a specially designed IM to provide additional 
data to and from applications. The two methods are prototyped as 


HRESULT IInputMethod::GetImData (DWORD dwSize, void* pvimData); 


HRESULT IInputMethod::SetImData (DWORD dwSize, void* pvImData); 


For both of these functions, the pointer points to a block of memory in the applica- 
tion. The dwSize parameter contains the size of the block pointed to by pulmData. 

When an application is sending data to a custom IM, it calls SHSipInfo with 
the SPI_SETSIPINFO flag. The pointer to the buffer and the size of the buffer are 
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specified in the pulmData and dwImDataSize fields of the SIPINFO structure. If these 
two fields are nonzero, the input panel then calls the Set/mData method with the 
pointer and the size of the buffer contained in the two parameters of the method. 
The input method then accepts the data in the buffer pointed to by pulmData. When 
an application calls SHSipInfo with the SPI_LGETSIPINFO structure and nonzero val- 
ues in pulmData and dwImDataSize, the input panel then calls the Get/mData method 
to retrieve data from the input method. 


IinputMethod::Deselect 

When the user or a program switches to a different default IM, the input panel calls 
Deselect. Your input method should save its state Gits location on the screen, for ex- 
ample), destroy any windows it has created, and unregister any window classes it 
has registered. It should also destroy any image lists it’s still maintaining. The proto- 
type for this method is 


HRESULT IInputMethod::Deselect (void); 


After the Deselect method is called, the SIP will unload the input method DLL. 


IinputMethod::UserOptionsDig 

The UserOptionsDig method isn’t called by the input panel. Instead, the input panel’s 
control panel applet calls this method when the user clicks on the Options button. 
The IM should display a dialog box that allows the user to configure any settable 
parameters in the input method. The UserOptionsDig method is prototyped as 


HRESULT IInputMethod::UserOptionsDlg (HWND hwndParent) ; 


The only parameter is the handle to the window that should be the parent window 
of the dialog box. Because the IM might be unloaded after the dialog box is dismissed, 
any configuration data should be saved in a persistent place such as the registry, where 
it can be recalled when the input panel is loaded again. 


The /iMCallback interface 


The IIMCallback interface allows an IM to call back to the input panel for services 
such as sending keys to the operating system. Aside from the standard JUnknown 
methods that can be ignored by the IM, only four methods are exposed by IIMCallback. 
These methods are 


@ 8 IlMCallback::SetImInfo Sets the bitmaps used by the input panel as well 
as the location and visibility state of the input method 


M I[IMCallback::SendVirtualKey Sends a virtual key to the system 
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BM IMCallback::SendCharEvents Sends Unicode characters to the window 
with the current focus 


@ UMCallback::SendString Sends a string of characters to the window with 
the current focus 


It’s appropriate that the ZMCallback interface devotes three of its four methods 
to sending keys and characters to the system because that’s the primary purpose of 
the IM. Let’s take a quick look at each of these methods. 


1IMCallback::Setiminfo 

The SetiImInfo method allows the IM control over its size and location on the screen. 
This method can also be used to set the bitmaps representing the IM. The method is 
prototyped as 


HRESULT IIMCallback::SetImInfo (IMINFO *pimi); 


The only parameter is a pointer to an IMINFO structure. This is the same structure 
that the IM uses when it calls the GetInfo method of the IImputMethod interface, but 
ll repeat it here for clarity. 


typedef struct { 
DWORD cbSize; 
HANDLE hImageNarrow; 
HANDLE hImageWide; 
int iNarrow; 
int iWide; 
DWORD fdwFlags; 
RECT rcSipRect; 
} IMINFO; 


This structure enables an IM to tell the input panel the information that the panel 
asked for in GetInfo. The IM must correctly fill in all the fields in the IMINFO struc- 
ture because it has no other way to tell the input panel to look at only one or two of 
the fields. You shouldn’t re-create the image lists when you're calling SetImInfo, in- 
stead, use the same handles you passed in Get/nfo unless you want to change the 
image lists used by the input panel. In that case, you'll need to destroy the old image 
lists after you’ve called SetImInfo. 

You can use SetimInfo to undock the input panel and move it around the screen 
by clearing the SIPF_DOCKED flag in fdwFlags and specifying a new size and loca- 
tion for the panel in the rcSipRect field. Because Windows CE doesn’t provide sys- 
tem support for dragging an input panel around the screen, the IM is responsible for 
providing such a method. The sample IM I present beginning on page 766 supports 
dragging the input panel around by creating a gripper area on the side of the panel 
and interpreting the stylus messages in this area to allow the panel to be moved around 
the screen. 
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liMCaliback::SendVirtualKey 

The SendVirtualKey method is used to send virtual key codes to the system. The dif- 
ference between this method and the SendCharEvents and SendString methods is that 
this method can be used to send noncharacter key codes, such as those from cursor 
keys and shift keys, that have a global impact on the system. Also, key codes sent by 
SendVirtualKey are affected by the system key state. For example, if you send an a 
character and the Shift key is currently down, the resulting WM_CHAR message con- 
tains an A character. SendVirtualKey is prototyped as 


HRESULT IIMCallback::SendVirtualKey (BYTE bVk, DWORD dwFlags); 


The first parameter is the virtual key code of the key you want to send. The second 
parameter can contain one or more flags that help define the event. The flags can be 
either 0 or a combination of flags. You would use KEYEVENTF_KEYUP to indicate 
that the event is a key up event as opposed to a key down event and KEYEVENTF_ 
SILENT, which specifies that the key event won’t cause a key click to be played for 
the event. If you use SendVirtualKey to send a character key, the character will be 
modified by the current shift state of the system. 


liMCaliback::SendCharEvents 

The SendCharEvents method can be used to send specific characters to the window 
with the current focus. The difference between this method and the SendVirtualKey 
method is that SendCharEvents gives you much more control over the exact infor- 
mation provided in the WM_KEYx«x. and WM_CHAR messages generated. Instead 
of simply sending a virtual key code and letting the system determine the proper 
character, this method allows you to specify the virtual key and associate a completely 
different character or series of characters generated by this event. For example, in a 
simple case, calling this method once causes the messages WM_KEYDOWN, WM_ 
CHAR, and WM_KEYUP all to be sent to the focus window. In a more complex case, 
this method can send a WM_KEYDOWN, and multiple WM_CHAR messages, followed 
by a WM_KEYUP message. 

This method is prototyped as 


HRESULT IIMCallback::SendCharEvents (UINT uVK, UINT uKeyFlags, 
UINT uChars, UINT *puShift, UINT *puChars); 


The first parameter is the virtual key code that will be sent with the WM_KEYDOWN 
and WM_KEYUP messages. The second parameter is the key flags that will be sent 
with the WM_KEYDOWN and WM_KEYUP messages. The third parameter is the 
number of WM_CHAR messages that will be generated by this one event. The next 
parameter, puShift, should point to an array of key state flags, while the final param- 
eter, puChar, should point to an array of Unicode characters. Each entry in the shift 
array will be joined with the corresponding Unicode character in the character array 
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when the WM_CHAR messages are generated. This allows you to give one key on 
the IM keyboard a unique virtual key code and to generate any number of WM_CHAR 
messages, each with its own shift state. 


liMCallback::SendString 

You use the SendString method to send a series of characters to the focus window. 
The advantage of this function is that an IM can easily send an entire word or sen- 
tence, and the input panel will take care of the details such as key down and key up 
events. The method is prototyped as 


HRESULT IIMCallback::SendString (LPTSTR ptszStr, DWORD dwSize); 


The two parameters are the string of characters to be sent and the number of charac- 
ters in the string. 
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The NumPanel example code demonstrates a simple IM. NumPanel gives a user a 
simple numeric keyboard including keys 0 through 9 as well as the four arithmetic 
operators, +, —, *, and / and the equal sign key. While not of much use to the user, 
NumPanel does demonstrate all the requirements of an input method. The NumPanel 
example is different from the standard IMs that come with the Palm-size PC in that it 
can be undocked. The NumPanel IM has a gripper bar on the left side of the window 
that can be used to drag the SIP around the screen. When a user double-taps the gripper 
bar, the SIP snaps back to its docked position. Figure 13-2 shows the NumPanel IM 
in its docked position while Figure 13-3 shows the same panel undocked. 
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Figure 13-2. The NumPanel IM window in its docked position. 
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Figure 13-3. 7he NumPanel IM window undocked. 


The source code that implements NumPanel is divided into two main files, 
NumPanel.cpp and NPWnd.c. NumPanel.cpp provides the COM interfaces necessary 
for the IM, including the IInputMethod interface and the /ClassFactory interface. In 
this file as well is Di/Main, and the other functions necessary to implement a COM 
in-proc server. NPWnd.c contains the code that implements the NumPanel window. 
This code comprises the NumPanel window procedure and the supporting message 
handling procedures. The source code for NumPanel is shown in Figure 13-4. 


Figure 13-4. 7he NumPanel source code. (continued) 
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Although NumPanel is divided into two source files, both the IInputMethod 
interface and the NumPanel window procedure run in the same thread. In response 
to a call to the Select method of IImputMethod, the NumPanel window class is regis- 
tered and the window is created as a child of the IM’s window. The image lists used 
by the IM are also created here with the handles stored in member variables in the 
MyInputMethod object. The only other work of interest performed by the code in 
NumPanel.cpp is the code for the GetInfo method. In this method, the image list 
handles are provided to the IM along with the requested dimensions of the undocked 
window. The dimensions of the docked window are provided by the system. 

For three other methods, all MyInputMethod does is to post messages to the 
window procedure of the NumPanel window. In NMWnd.c, these messages are fielded 
in the MYMSG_METHCALL user-defined message. The three methods make available 
to the window a pointer to the IMCallback interface and notify the NumPanel win- 


dow that the window is about to be displayed or that the state of the input panel is 
changing. 
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The other code in the NumPanel window draws the keys on the window and 
processes the stylus taps. The DoPaintSip routine handles the painting. The routine 
draws a grid of 3 rows of 5 columns of buttons. In each button, a character is drawn 
to label it. A separate bit array contains the up or down state of each button. If the 
button is down, the background of the button is drawn in reverse colors. 

Two routines—DoMouseSip and HandleGripper —handle the mouse messages. 
The mouse messages all initially go to DoMouseSip, which calls HandleGripper. If the 
routine determines that the mouse message is on the gripper or that the window is 
currently being dragged, HandleGripper handles the message. Otherwise, if the 
DoMouseSip routine determines that a mouse tap occurs on one of the buttons, it calls 
the SendCharEvent method of IMCallback to send the character to the focus window. 

When the window is dragged to a new location on the screen, the HandleGripper 
routine clears the SIPF_DOCKED flag and sets the new size and location of the SIP 
by calling the SetImInfo method of IIMCallback. When the user double-taps on the 
gripper, HandleGripper sets the SIPF_DOCKED flag and sets the SIP rectangle to 
the original docked rectangle that was saved when the NumPanel window was first 
created. 


HARDWARE KEYS 


The SIP isn’t the only way for the user to enter keystrokes to an application. All Palm- 
size PCs and some Handheld PCs have additional buttons that can be assigned to 
launch an application or to send unique virtual key codes to applications. The Palm- 
size PC has an additional set of buttons known as navigation butions that mimic 
common navigation keys such as Line Up and Line Down. These navigation keys give 
the user shortcuts, which allow scrolling up and down as well as access to the ser- 
vices of the often-used keys, Enter and Escape. Because the scrolling buttons simply 
send Page Up, Page Down, Line Up, and Line Down key messages, your application 
doesn’t have to take any special action to use these keys. 

The application launch buttons are another matter. When pressed, these keys 
cause the shell to launch the application registered for that key. Although a system is 
usually configured with default associations, you can override these settings by modi- 
fying the registry so that pressing a hardware control button launches your applica- 
tion. An application can also override the application launch ability of a specific key 
by having the key mapped directly to a window. In addition, you can use the hot 
key features of GWE to override the hardware key assignment and send a hot key 
message to a window. 
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Since the hardware control buttons are treated as keyboard keys, pressing a hard- 
ware control key results in WM_KEYDOWN and WM_KEYUP messages as well as a 
WM_CHAR message if the virtual key matches a Unicode character. The system map- 
ping of these keys employs two strategies. For the navigation keys, the resulting vir- 
tual key codes are codes known and used by Windows applications so that those 
applications can “use” the keys without even knowing that’s what they’re doing. The 
application-launching keys, on the other hand, need virtual key codes that are com- 
pletely different from previously known keys so that they won’t conflict with stan- 
dard key events. 


Navigation key codes 
As I mentioned above, the navigation keys are mapped to common navigation keys. 
The actual virtual key code mapping for navigation keys is shown below. 


Key Action Key Message Key Code 
Action Press WM_KEYDOWN OEM dependent* 
Action Release WM_KEYUP OEM dependent* 
WM_KEYDOWN VK_RETURN 
WM_CHAR VK_RETURN 
WM_KEYUP VK_RETURN 
Exit Press WM_KEYDOWN OEM dependent* 
Release WM_KEYUP OEM dependent* 
WM_KEYDOWN VK_ESCAPE 
WM_KEYUP VK_ESCAPE 
Rock Up Press WM_KEYDOWN OEM dependent* 
Release WM_KEYUP OEM dependent* 
WM_KEYDOWN VK_UP 
WM_KEYUP VK_UP 
Rock Down Press WM_KEYDOWN OEM dependent* 
Release WM_KEYUP OEM dependent* 
WM_KEYDOWN VK_DOWN 
WM_KEYUP VK_DOWN 


* OEM-dependent key codes differ from system to system. Some OEMs might not send these mes- 
sages while others may send the messages with a virtual key code of 0. 


Unfortunately, there’s no reliable way of determining whether a VK_RETURN 
key event came from the SIP or from a hardware button. Each OEM has a different 
method of assigning virtual key codes to the hardware navigation buttons. 
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Application launch key codes 

The shell manages the application launch keys named App] through a possible App16. 
These keys produce a combination of virtual key codes that are interpreted by the 
shell. The codes produced are a combination of the left Windows key (VK_LWIN) 
and a virtual code starting with 0xC1 and continuing up, depending on the applica- 
tion key pressed. For example, App1 key produces the virtual key sequence VK_LWIN 
followed by 0xC1 while App2 key produces the sequence VK_LWIN followed by 0xC2. 


Using the Application Launch Keys 


Applications are bound to a specific application launch key through entries in the 
registry. Specifically, each key has an entry under [HKEY_LOCAL_MACHINE]\ 
Software \ Microsoft\Shell\Keys. The entry is the virtual key combination for that key, 
so for the App! key, the entry is 


[HKEY_LOCAL_MACHINE]\Software\Microsoft\Shel1\Keys\4@C1 


The 40C1 comes from the code 0x40, which indicates the Windows key has been 
pressed and concatenated with the virtual key code of the application key, 0xC1. The 
default value assigned to this key is the fully specified path name of the application 
assigned to the key. A few other values are also stored under this key. The ResetCmd 
value is the path name of the application that is assigned to this key if the Restore 
Defaults button is pressed in the Palm-size PC’s Button control panel applet. The Name 
value contains the friendly name of the key, such as Button 1 or Side Button. 

The only way to change the application assigned to a key is to manually change 
the registry entry to point to your application. Of course, you shouldn’t do this with- 
out consulting your users, since they may have already configured the application 
keys to their liking. The routine that follows assigns an-application to a specific but- 
ton and returns the name of the application previously assigned to that button. The 
vkAppKey parameter should be set to an application key virtual key code, 0xC1 through 
OxCF. The pszNewApp parameter should point to the fully specified path name of the 
application you want to assign to the key. 


// SetAppLaunchKey - Assigns an application launch key to an 
// application 
// 
int SetAppLaunchKey (LPTSTR pszNewApp, BYTE vkAppKey, LPTSTR pszOldApp, 
INT nOldAppSize) {| 
TCHAR szKeyName[256]; 
DWORD dwType, dwDisp; 
HKEY hKey; 
INT re; 
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// Construct the key name. 
wsprintf (szKeyName, 
TEXT ("Software\\Microsoft\\Shell\\Keys\\40%02x"), vkAppKey); 


// Open the key. 
rc = RegCreateKeyEx (HKEY_LOCAL_MACHINE, szKeyName, @, TEXT (""), 
@, @, NULL, &hKey, &dwDisp); 
if (rc != ERROR_SUCCESS) 
return -1; 


// Read the old application name. 
re = RegQueryValueEx (hKey, TEXT (""), 0, &dwType, 
(PBYTE)pszOldApp, &nOldAppSize); 
if (re != ERROR_SUCCESS) { 
RegCloseKey (hKey); 
return -2; 


// Set the new application name. 
re = RegSetValueEx (hKey, TEXT (""), @, REG_SZ, (PBYTE)pszNewApp, 
(Ilstrilen (pszNewApp)+1) * sizeof (TCHAR)); 
RegCloseKey (hKey); 
if (rc != ERROR_SUCCESS) 
return -3; 


return Q; 


When an application button is pressed, the system doesn’t check to see whether 
another copy of the application is already running—it simply launches a new copy. 
You should design your application, especially on the Palm-size PC, to check to see 
whether another copy of your application is already running and if so, to activate the 
first copy of the application and quietly terminate the newly launched copy. 

You can determine whether an application is assigned to a key by calling the 
Palm-size PC-specific function SHGetAppKeyAssoc, which is prototyped as 


Byte SHGetAppKeyAssoc (LPCTSTR ptszApp); 


The only parameter is the fully qualified name of your application. If a key is associ- 
ated with your application, the function returns the virtual key code for that key. If 
no key is associated with your application, the function returns 0. This function is 
useful because most applications, when launched by an application key, override the 
default action of the key so that another copy of the application won't launch if the 
key is pressed again. 
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Dynamically Overriding Application Launch Keys 


A running application can override a launch key in two ways. The first method is to 
use the Palm-size PC-specific function SHSetAppKeyWndAssoc, prototyped as 


BOOL SHSetAppKeyWndAssoc (BYTE bVk, HWND hwnd); 


The first parameter is the virtual key code of the hardware button. The second pa- 
rameter is the handle of the window that’s to receive the notices of button presses. 
For example, a program might redirect the App1 key to its main window with the 
following line of code: 


SHSetAppKeyWndAssoc (@xC1, hwndMain) ; 


The window that has redirected an application might receive key messages but the 
virtual key codes received and the type of key messages are OEM-specific. The chief 
reason for using SHSetAppKeyWndAssoc is to prevent the button from launching an 
application. When you no longer want to redirect the application launch key, you 
can call SHSetAppKeyWndAssoc specifying the virtual code of the key and NULL for 
the window handle. 

The second method of overriding an application launch key is to use the Register- 
HotKey function. The advantage of using the RegisterHotKey function is that your 
window will receive known messages, albeit WM_HOTKEY instead of WM_KEYxxx 
messages when the key is pressed, no matter what application currently has the key- 
board focus. A second, even more important reason to use RegisterHotKey is that this 
function is supported on Handheld PCs as well as on Palm-size PCs. This function is 
prototyped as 


BOOL RegisterHotKey (HWND hWnd, int id, UINT fsModifiers, UINT vk); 


The first parameter is the handle of the window that receives the WM_HOTKEY 
messages. The second parameter is an application-defined identifier that’s included 
with the WM_HOTKEY message to indicate which key caused the message. The 
fsModifiers parameter should be set with flags, indicating the shift keys that must also 
be pressed before the WM_HOTKEY message can be sent. These self-explanatory 
flags are MOD_ALT, MOD_CONTROL, MOD_SHIFT, and MOD_WIN. An additional 
flag, MOD_KEYUP, indicates that the window will receive WM_HOTKEY messages 
when the key is pressed and when the key is released. When using RegisterHotKey 
on application keys, you should always specify the MOD_WIN flag because applica- 
tion keys always are combined with the Windows shift-modifier key. The final pa- 
rameter, vk, is the virtual key code for the key you want as your hot key. This key 
doesn’t have to be a hardware key code; you can actually use almost any other vir- 
tual key code supported by Windows, although assigning Shift-F to your custom fax 
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application might make Pocket Word users a bit irate when they tried to enter a 
capital F. 

When the key registered with RegisterHotKey is pressed, the system sends a 
WM_HOTKEY message to the window. The wParam parameter contains the ID code 
you specified when you called RegisterHotKey. The low word of [Param parameter 
contains the shift-key modifiers, MOD_xxx, that were set when the key was pressed, 
while the high word of [Param contains the virtual key code for the key. 

The disadvantage of using RegisterHotKey is that if another application has al- 
ready registered the hot key, the function will fail. This can be problematic on the 
Palm-size PC, where applications stay running until the system purges them to gain 
extra memory space. One strategy to employ when you want to use a hardware 
key temporarily—for example, in a game—would be to use SHGetAppKeyAssoc to 
determine what application is currently assigned to that key. It’s a good bet that if 
kegisterHotKey failed due to some other program using it, the application assigned 
the application key is also the one currently running and has redirected the hot key 
to its window. You can then send a WM_CLOSE message to that application’s main 
window to see whether it will close and free up the hardware key. 

When you no longer need the hot key, you can unregister the hot key with this 
function: 


BOOL UnregisterHotKey (HWND hWnd, int id); 


The two parameters are the window handle of the window that had registered the 
hot key and the ID value for that hot key you assigned with RegisterHotKey. 

As you can see, the Palm-size PC presents new problems and new opportuni- 
ties for developers. The SIP technology, originally developed for the Palm-size PC, is 
already starting to migrate to other Windows CE platforms. The application launch 
buttons are another area of cross platform cooperation. You use the same techniques 
for managing these buttons on H/PCs as on Palm-size PC devices. 

In the final chapter of the book, I step back from application programming and 
look at system programming issues. Chapter 14 explains how the different compo- 
nents of Windows CE work together while presenting a unified Win32-compatible API. 


Chapter 14 


System 
Programming 


This chapter takes a slightly different tack from the previous chapters of the book. 
Instead of touring the API of a particular section of Windows CE, I'll show you Win- 
dows CE from a systems perspective. 

Windows CE presents standard Windows programmers some unique challenges. 
First, because Windows CE supports a variety of different microprocessors and sys- 
tem architectures, you can’t count on the tried and true IBM/Intel PC-compatible design 
that can be directly traced to the IBM PC/AT released in 1984. Windows CE runs on 
devices that are more different than alike. Different CPUs use different memory lay- 
outs and while the set of peripherals are similar, they have totally different designs. 

In addition to using different hardware, Windows CE itself changes, depending 
on how it’s ported to a specific platform. While all H/PCs of a particular version have 
the same set of functions, that set is slightly different from the functions provided by 
Windows CE for the Palm-size PC. In addition, Windows CE is designed as a collec- 
tion of components so that OEMs using Windows CE in embedded devices can re- 
move unnecessary small sections of the operating system, such as the Clipboard API. 

All of these conditions make programming Windows CE unique, and I might 
add, fun. This chapter describes some of these cross-platform programming issues. 
Pll begin the chapter by describing how the system boots itself, from reset to running 
applications. 
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E BOOT PROCESS 


If you’re a systems programmer, you might enjoy, as I do, seeing how a system boots 
up. When you think about it, booting up poses some interesting problems. How does 
the system load its first process when the process loader is part of that process you 
want to load? How do you deal with 30 different CPUs, each with its own method of 
initialization? 

In the case of Windows CE, we have a somewhat better view of this process. 
Because the hardware varies radically across the different platforms, Windows CE 
requires that OEMs write some of the initialization code. In each instance, this initial- 
ization code is incorporated in the HAL (hardware abstraction layer), under the ker- 
nel. When an OEM builds the system for a specific hardware platform, the HAL is 
statically linked with the Windows CE kernel code to produce NK.exe. 

Actually, the OEM writes far more than the HAL when porting Windows CE to 
a new platform. The OEM also writes a thin layer under the Graphics Windowing 
and Event Manager (GWE) to link in some of the more basic drivers used by GWE. 
In addition, the OEM must write a series of device drivers, from a display device driver 
to drivers for the keyboard, touch panel, serial, and audio devices. The actual collec- 
tion of drivers is, of course, dependent on the hardware. This collection of the HAL 
layer plus the drivers is called the OEM Adaptation Layer, or OAL. 

In any case, let’s get back to the boot process. This boot process is described 
through the documentation and code examples provided in the Embedded Tool Kit. 
Our journey starts, as with any CPU, at the occurrence of a reset. 


Reset 


When the system is reset, the CPU jumps to the entry point of NK.exe, which is the 
kernel module for Windows CE.' The code at the entry point is actually written by 
the OEM, not Microsoft. This routine, written in assembler, is traditionally named 
Startup and is responsible for initializing the CPU into a known state for the kernel. 
Since most CPUs supported by Windows CE are embedded CPUs, they generally have 
a number of registers that must be set to configure the system for the speed and some- 
times even the base address of memory. Startup is also responsible for initializing any 
caches and for ensuring that the system is in an uncached, flat addressing mode. 


NK.exe 


794 


When Startup has completed its tasks, it jumps to the entry point of the kernel, 
KernelStart. This is the entry point for the Microsoft written code for NK. KernelStart 
configures the virtual memory manager, initializes the interrupt vector table to a 


1. The program that builds the ROM image inserts the proper jump instructions, or vector, at the re- 
set location, which causes the CPU to start executing code at the entry point of NK. 
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default handler, and calls down to the OEM layer to initialize the debug serial port.’ 
KernelStart then initializes its local heap by copying the initialized heap data from 
ROM into system RAM, in a routine named KernelRelocate. Now that the local heap 
for NK.exe has been initialized, the code can start acting less like a loader and more 
like a program. The kernel then calls back down to the HAL to the OEM/nit routine. 

The job of OEMInit, which is customarily written in C, is to initialize any OEM- 
specific hardware. This includes hooking interrupts, initializing timers, and testing 
memory.’ Many systems perform some initial configuration of integrated peripher- 
als, if only to place them in a quiescent state until the driver for that peripheral can 
be loaded. The OEM/nit routine is generally responsible for drawing the splash screen 
on the display during a boot process. 

When OEFM/nit returns, the kernel calls back into the HAL to ask whether any 
additional RAM is available to the system. When an OEM creates a ROM image of the 
Windows CE files, it makes some preliminary estimates about the size and location 
of the RAM as well as defining the size and location of the ROM. This routine, 
OEMGetExtensionDRAM, allows the OEM to tell the kernel about additional RAM that 
can be used by the system. Once OEMGetExtensionDRAM returns, the kernel enables 
interrupts and calls the scheduler to schedule the first thread in the system. 


FileSys.exe 

At this point, the kernel looks for the file FileSys.exe and launches that application. 
FileSys is the process that manages the file system, the database functions, and more 
important at this stage, the registry. When FileSys is loaded, it looks in the RAM to 
see whether it can find a file system already initialized. If one is found, FileSys uses 
the already initialized file system. This allows Windows CE devices to retain the data 
in their RAM-based file systems over a reboot of the system. 

If FilSys doesn’t find a file system, it creates one that merges an empty RAM file 
system with the files on ROM. FileSys knows what files are in ROM by means of a 
table that’s built into the ROM image by the ROM builder program, which merged all 
the disparate programs into one image. FileSys reads the default directory structure 
from a file stored on ROM, which is composed of entries suggested by Microsoft for 
the OEM. In addition to initializing the file system, FileSys creates default database 
images and a default registry. The initial images of the default databases and default 
registry are also defined in files in ROM written by the OEM and Microsoft. This file- 
driven initialization process allows OEMs to customize the initial images of the file 
system from the directory tree to the individual entries in the registry. 


2. All Windows CE systems, including all H/PCs and Palm-size PCs, have a way to access a dedicated 
serial port used for debugging. For consumer platforms, where controlling hardware cost is criti- 
cal, this debug serial port is typically on a separate “debug board” that can be plugged into a 
system. 


3. It’s the OEM’s decision whether to run a RAM test when the system boots. Microsoft requires only 
that the system boot process is complete within 5 or so seconds. 
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One other feature of FileSys acts like a back door to the file system. During 
initialization, FileSys looks to see whether the system is connected to a debugging 
station, which is a PC running a program named CESH.‘ Traditionally, the connec- 
tion between the PC and the Windows CE system was a parallel port link. However, 
starting with Windows CE 2.1, this link can be made over Ethernet or a dedicated 
serial link. If such a connection is found, FileSys takes the additional step of looking 
on the PC for files when the system asks it to load a file. In effect, this seamlessly 
extends the \windows directory on the Windows CE system to include any files in a 
specific directory on the debugging PC. This procedure allows the system to load files 
that aren’t in the initial ROM image during the boot process. Later, when the system 
is running, files can be directly loaded from the PC without your first having to copy 
them into the object store of the Windows CE system. 


Launching optional processes 

Once FileSys has initialized, the system initialization can proceed. The kernel needs 
to wait because, at this point, it needs data from the registry to continue the boot 
process. Specifically, the kernel looks in the registry for values under the key [HKEY_ 
LOCAL_MACHINE]\Init. The values in this key provide the name, order, and depen- 
dencies of a set of processes that should be loaded as part of the boot process. The 
processes to be launched are specified by values named Launchxx where the xx is a 
number defining the order of the launch. An optional value, Dependxx, can be used 
to make the launch of a process dependent on another process specified earlier in 
the order. For example, the following set of values was take from the registry of a 
Casio Handheld PC. 


Value Data Comments 

Launchl@ SHELL. EXE 

Launch2Q DEVICE.EXE 

Launch3@ GWES.EXE 

Depend3@ 0014 Depends on Device (@x14 == 20) 
Launch5@ EXPLORER.EXE 

Depend5@ 0014 QO1E Depends on Device and GWE 


While I’ve listed the values in their launch order for clarity, the values don’t need 
to be in order in the registry. The numbers embedded in the names of the values define 
the launch order. 

The kernel loads each of the modules listed in their own process space. When 
a process completes its initialization successfully, it signals this event to the kernel 


4. CESH is a PC-based debugging tool provided by Microsoft in the ETK. It was called PPSH, for par- 
allel port shell, before the release of Windows CE 2.1. 
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by calling the function SignalStarted and passing the application’s launch number. 
The kernel knows from these calls to SignalStarted that any dependent processes can 
now be launched. 

What’s interesting here is that each of these components of the operating sys- 
tem functions as a standard user-level process. Just because a process appears in this 
list doesn’t mean that it’s part of the operating system. While this launch list is gener- 
ally used only by OEMs, you can insert other processes in this list, as long as the func- 
tions needed by that application have been loaded earlier in the list. For example, 
you could write an application that’s loaded after Device and before GWES.exe as 
long as that application didn’t make any calls to the window manager or the graph- 
ics functions until GWE is initialized. On the other hand, launching an application 
with a standard user interface before Explorer loads can confuse Explorer. So unless 
you need to launch a process to support system services, you should use Explorer to 
launch your applications on startup. One additional point—you can't separately launch 
an application that depends on Explorer to launch successfully because Explorer.exe 
doesn’t call SignalStarted during its initialization. Now let’s follow this sequence and 
examine each of these launched processes. 


Shell.exe 

Shell is an interesting process because it’s not even in the ROM of most systems. 
Shell.exe is the Windows CE side of CESH, the command line—based monitor. Be- 
cause Shell.exe isn’t in the ROM, the only way to load it is by connecting the system 
to the PC debugging station so that the file can be automatically downloaded from 
the PC. 

CESH uses the FileSys link to the debugging PC to communicate with the pro- 
grammer. Instead of opening a file on the PC, CESH opens a console session on the 
PC. The CESH debugger provides a number of useful functions to the Windows CE 
OEM. First it gives the OEM developer a command line shell, running on a PC that 
can be used to launch applications, query system status, and read and write memory 
on the system. 

CESH also lets the OEM developer manipulate a very handy feature of debug 
builds of Windows CE named debug zones. When you’re developing software, it’s 
often useful to insert debugging messages that print out information. On a Windows 
CE system, these debugging messages are sent via the debug serial port. The prob- 
lem is that too many messages can hide a critical error behind a blizzard of irrelevant 
informational messages. On the other hand, Murphy says that the day after you strip 
all your debugging messages from a section of code, you'll need those messages to 
diagnose a newly reported bug. Debug zones allow the developer to interactively 
enable and disable sets of debug messages that are built into debug builds of Win- 
dows CE. All of the base processes bundled with Windows CE as well as all the de- 
vice drivers have these debugging messages built into them. Every message is assigned 
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to one of 16 defined debug zones for that process or DLL. So, a developer can use 
CESH to enable or disable each of the 16 zones for a module, which enables or dis- 
ables the messages for that zone. 

Shell.exe uses a Windows CE version of toolhelp.dll, so when Shell loads, it loads 
ToolHelp. Shell doesn’t bring any additional function to Windows CE; it’s just one 
place where Microsoft has added built-in debugging features for the OEM. 


Device.exe 

After Shell, the next module in the launch list is Device.exe. Notice that there’s no 
Depened20 line that makes the launch of Device.exe dependent on Shell.exe. That’s 
important because Shell won’t launch successfully unless the system has Shell.exe in 
the object store or is connected to a debug station. The job of Device.exe is to load 
and manage the installable device drivers in the system. This includes managing any 
PCMCIA Card drivers that must be dynamically loaded and freed as well. 

When Device.exe loads, it first loads the PCMCIA driver. It then looks in the 
registry under [HKEY_LOCAL_MACHINE\BuiltIn for the list of the other drivers it must 
load when it initializes. This list is contained in a series of keys. The names of the 
keys don’t matter—it’s the values contained in the keys that define which drivers to 
load and the order in which to load them. Figure 14-1 shows the contents of the 
WaveDev key. The Wave driver is the audio driver. 
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The four values under this key are the basic four entries used by a device driver 
under Windows CE. The Prefix value defines the three-letter name of the driver. 
Applications that want to open this driver use the three-letter key with the number 
that Windows CE appends to create the device name. 

The Index value is the number that will be appended to the device name. The 
Dll key specifies the name of the DLL that implements the driver. This is the DLL that 
Device.exe loads. 

The Order value allows the OEM to recommend the order in which the drivers 
are loaded. Device.exe loads drivers with lower Order values before drivers with higher 
Order values in the registry. As Device.exe reads each of the registry keys, it loads 
the DLL specified, calls RegisterDevice to register the DLL as a device driver with the 
system, and then unloads the DLL. The DLL stays in memory because RegisterDevice 
increments the use count of the DLL. 

While this is the standard load procedure, you can use another method. If the 
driver key contains a value named Entry, Device loads the DLL, and then, instead of 
calling RegisterDevice, it calls the entry point in the driver named in Entry. The driver 
is then responsible for calling the RegisterDevice function on its own so that it will be 
registered as a driver with the system. 

The Entry value allows OEMs to fine-tune the loading process for a driver, if 
necessary. If the Entry key is present, another key, Keep, can also be specified. Speci- 
fying the Keep key tells Device.exe not to attempt to unload the driver after it calls 
the driver’s entry point. This allows the driver DLL to avoid calling RegisterDevice and 
therefore avoid being a driver at all. Instead, the DLL is simply loaded into the pro- 
cess space of Device.exe. | 

One of the subtle points about having Device.exe load the installable drivers is 
that all these drivers will execute in the same 32-MB process space of Device.exe. 
This coincidence allows related drivers to actually directly call entry points in each 
other, although the preferred method would be to formally make an IOCTL call into 
the other driver. You can’t count on this common process arrangement in future ver- 
sions of Windows CE. 


GWES.exe 
Referring again to the list in the registry, we see that the next module to be loaded is 
GWES.EXE. GWES.exe contains the GWE subsystem. As I mentioned earlier in the 
book, GWE stands for Graphics Windowing and Event Manager. Essentially, GWES 
is the graphical user interface over the top of the base operating system composed of 
NK, FileSys, and Device. 

Because GWE forms the user interface of a graphical version of Windows CE, 
it’s not too surprising that the drivers that directly access the user interface hardware, 
the keyboard, the touch panel, and the display are loaded by GWES.exe instead of 
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Device.exe. A “pure” operating system design would isolate these drivers with the 
others, down in the kernel. Given the lightweight nature of Windows CE, however, 
having these drivers loaded by GWE makes a faster and simpler interface for the 
operating system. These drivers also don’t support the standard stream interface re- 
quired of drivers loaded by Device.exe. Instead, each driver has a custom set of en- 
try points called by GWES.exe. 

Unlike device.exe, GWES.exe doesn’t load just any set of drivers. Instead, GWE 
simply loads three predefined drivers: the keyboard driver, the touch panel driver, 
and the display driver. GWES.exe looks in the registry in the following keys to find 
these drivers all under the root registry key of [HKEY_LOCAL_MACHINE]: 


Driver Registry Key Name Value Name 
Keyboard \HARDWARE\DEVICEMAP\KEYBD DriverName 
Touch Panel \HARDWARE\DEVICEMAP\TOUCH DriverName 
Display \SYSTEM\GDI\DRIVERS Display 


If the registry entries aren’t found for a particular driver, GWES.exe uses default 
names for that driver. These drivers are written by the OEM and are called native drivers 
to differentiate them from the installable form of a driver loaded by Device. 

In addition to the drivers loaded by GWE, the OEM also is charged with writing 
a small amount of system adaptation code to support GWE. This code deals with 
providing information about the state of the battery and an interface to the notifica- 
tion LED, if one is present. Although this code can be statically linked to GWE when 
the system is built, many OEMs isolate this code into one or more DLLs and statically 
link only a small amount of code that loads these DLLs. 


Custom processes 

At this point in the boot process, Windows CE, as an operating system, is up and 
running. All that’s left is to launch the shell. Some OEMs, however, launch processes 
at this point that manage some OEM-specific tasks. Although you can launch other 
applications before you launch the Explorer, you should be careful about that, as I 
mentioned before. The Explorer isn’t written to handle visible top-level windows that 
are created before the Explorer. You can see this by inserting the following lines in 
the init key that launches Calc before the Explorer: 


Launch45 calc.exe 
Depend45 0014 QO1E 


After you insert the lines, reset your Windows CE device. Tap the desktop but- 
ton on the right end of the taskbar a couple of times and you'll see the Calc window. 
Pressing on the Pop-Up button reduces the size of the Calc window so you can again 
see the Explorer underneath. Notice that the taskbar doesn’t have a button for the 
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Calc window. Nor, if you press Alt-Tab, is Calc listed in the Active Tasks list. Figure 14-2 
shows this unusual arrangement of Calc and the Explorer on an H/PC. 


~The Internet 


~~ Calculator 


My s a : : Quic 


“Documents Ressicr pales ee ae ExpersAble 


Figure 14-2. The unusual arrangement of Calc and the Explorer. 


Because of the limitations of this arrangement, you shouldn’t launch applica- 
tions with a user interface before the Explorer is launched. On the other hand, if you 
have an application that doesn’t have a user interface but you need to launch before 
the shell, this is the time to do it. 


Explorer.exe 

Finally the list is terminated by the launch of the Explorer, or Shell32.exe, if the sys- 
tem is a Palm-size PC. The Explorer is, of course, the shell. Although the latest ver- 
sions of the Explorer add some functions to the API, the trend is to move as many 
functions as possible from the shell to the operating system. This allows developers 
of embedded systems to use those functions even if the system doesn’t include the 
Explorer. 

At this point, the location of the list of files launched during startup changes 
from the registry to the file system. After the Explorer initializes the desktop and the 
taskbar window, it looks in the \windows\startup directory and launches any 
executables or shortcuts contained in that directory. This is the standard, user- 
accessible method for launching applications when the system starts. This auto launch- 
ing is part of the Explorer, so if you’re building an embedded system without the 
Explorer, you’ll have to perform this last task yourself. 


Powering Up Doesn’t Boot the System 


One thing to always remember in Windows CE is that for most configurations, in- 
cluding all battery-powered systems, pressing the Power button doesn’t reset the 
device. As I explained in Chapter 6, when the system is powered down it doesn’t 
really turn off. Instead, the system enters an extremely low power state in which all 
the peripherals and the CPU power down but the state of the RAM is maintained. 
When a user presses the power switch, the system restores power and simply returns 
to the thread that was executing when the power button was originally pressed. 
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Battery-powered Windows CE systems are reset only when power is initially 
applied to the system—that is, when the first set of batteries is put in the device. Other 
than that, resets occur only when the user presses the reset button that’s generally 
exposed through a pinhole somewhere on the case of the device. Memory isn’t erased 
when a user presses the reset switch, which allows FileSys to use the Object Store 
that was already in RAM before the reset. 


SYSTEM CONFIGURATION 


At this point, the system is up and running, but just what is running and how is it 
configured? Figure 14-3 shows the system after a reset has occurred. The diagram 
separates the individual processes into their memory slots. Remember that slot 0 is 
reserved for the currently active process. The list of DLLs that each process has loaded 
is shown below the name of the process. 


First user Last user 

NK.exe FileSys.exe |Device.exe |GWES.exe /|Explorer.exe |application application 
Coredil.dll Coredil.dll Coredil.dll Coredil.dll Coredil.dll Coredl.dil Coredll.dll 

PCMCIA.dll |DDI.dll WinSock.dll 

wavedev.dil jtouch.dll ASForm.dll 

Serial.dll keybddr.dil |old32.dll 

AFD.dll OEMLib.dll* |OleAut32.dll 

arp.dil CEShell.dil 

IrDAstk.dll commctrl.dll 

waveapi.dil webview.dll 

IRComm.dil imgdecmp.dil 

WinSock.dll WinINet.dll 

Tapi.dll 

Unimodem.dil 


SlotO  Slot1 Slot2 Slot3 Slot4 Slot5 Slot6 


* OEMLib.dll - Most OEMs have a DLL to support battery and notification LED. 


Slot 33 


Figure 14-3. 7he system configuration after the system starts up. 


Note that Coredl.dll is loaded by every process. Coredll provides the entry points for 
most APIs supported by Windows CE. As a call is made into Coredll.dll, it redirects 
the call to the appropriate server process—NK, FileSys, Device, GWE, or Explorer. 

Notice that Shell.exe isn’t shown in Figure 14-3. This is because when I cap- 
tured the information for this figure, the Windows CE device I was using wasn’t con- 
nected to a debug PC, so Shell.exe wasn’t loaded. 


WRITING CROSS-PLATFORM 
WINDOWS CE APPLICATIONS 


Over the years, Windows programmers have had to deal concurrently with different 
versions of the operating system. Part of the solution to the problem this situation 
posed was to call GetVersion or GetVersionEx and to act differently depending on 
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the version of the operating system you were working with. You can’t do that under 
Windows CE. Because of the flexible nature of Windows CE, two builds of the same 
version of Windows CE can have different APIs. The question remains, though, how 
do you support multiple platforms with a common code base? How does the operat- 
ing system version relate to the different platforms? 


Platforms and Operating System Versions 


To understand how the different platforms relate to the different versions of Win- 
dows CE, it helps to know how the Windows CE development team is organized within 
Microsoft. Windows CE is supported by a core OS group within Microsoft. This team 
is responsible for developing the operating system, including the file system and the 
various communication stacks. 

Coordinating efforts with the OS team are the various platform teams, working 
on the Handheld/PC, Palm-size PC, Auto PC, and Handheld/PC Pro as well as many 
other platforms yet to be announced. Each team is responsible for defining a sug- 
gested hardware platform, defining applications that will be bundled with the plat- 
form, and deciding which version of the operating system the platform will use. 
Because the OS team works continually to enhance Windows CE, planning new ver- 
sions over time, each platform team generally looks to see what version of Windows CE 
will be ready when that team’s platform ships. 

The individual platform teams also develop the shells for their platforms. Be- 
cause each team develops its own shell, many new functions or platform-specific 
functions first appear as part of the shell of a specific platform. Then if the newly 
introduced functions have a more general applicability, they’re moved to the base 
operating system in a later version. You can see this process in both the Notification 
API and the SIP API. Both these sets of functions started in their specific platform 
group and have now been moved out of the shell and are in the base operating 
system. 

Following is a list of the different platforms that have been released up to this 
point and the version of Windows CE that those platforms use. 


Platform Windows CE version 
Original H/PC 1.00 

Japanese release of H/PC 1.01 

H/PC 2.00 

Original Palm-size PC 2.01 

Windows CE 2.1 for 2.10 

embedded systems 

Handheld PC Pro 2.11 
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It’s not presently difficult to remember what platform is associated with which 
version of Windows CE, but this task will get more difficult as more platforms are 
added to the list. 

You can choose from a number of ways to deal with the problem of different 
platforms and different versions of Windows CE. Let’s look at a few. 


Compile-Time Versioning 
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The version problem can be tackled in a couple of places in the development pro- 
cess of an application. At compile time, you can use the preprocessor definition 
_WIN32_WCE to determine the version of the operating system you're currently build- 
ing for. By enclosing code in an #if preprocessor bracket, you can cause code to be 
compiled for specific versions of Windows CE. 

Following is an example of a routine that’s tuned both for the original Palm- 
size PC and for other platforms equipped with a SIP that are based on Windows CE 2.1. 


// 

// Get SIP rectangle. 

// 

void MyGetSipRect (RECT *prect) { 


#Fif _WIN32_WCE == 201 
SIPINFO si; 


memset (&si, 0, sizeof (si)); 

si.cbSize = sizeof (SIPINFO); 

// On original Palm-size PC, use old PPC Shell function. 
SHSipInfo (SPI_GETSIPINFO, @, &si, Q); 

*prect = si.rcSipRect; 


deelif _WIN32_WCE >= 210 
SIPINFO si: 


si.cbSize = sizeof (SIPINFO); 

// On Windows CE 2.1 or later, use new function. 
SipGetInfo (&si); 

*prect = si.rcSipRect; 


fFelse 

// Else, there isn't support for this function. 
#terror No SIP support. 
Htendif 

return; 


} 
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A virtue of this code is that linker links the appropriate function for the appro- 
priate platform. Without this sort of compile-time code, you couldn’t simply put a 
run-time ifstatement around the call to SHSipInfo because the program would never 
load on anything but a Palm-size PC. The loader wouldn't be able to find the exported 
function SHSipinfo in Coredll.dll because it’s present only in Palm-size PC versions 
of Windows CE. 

Builds for the Palm-size PC have an additional define set named Palm. So you 
can bracket Palm-size PC code in the following way: 


fHifdef Palm 
// Insert Palm-size PC code here. 
dtendif 


The reason I didn’t use the Palm define in the previous code is that I wanted to 
target specifically the original Palm-size PC, which used Windows CE version 2.01. 
Otherwise, if ’'d used the Palm define, that code would be included even when I 
was compiling for newer versions of the Palm-size PC, which will use a newer ver- 
sion of Windows CE. The problem with using conditional compilation is that while 
you still have a common source file, the resulting executable will be different for each 
platform. 


Explicit Linking 


You can tackle the version problem other ways. Sometimes one platform requires that 

you call a function different from one you need for another platform you’re working 

with but you want the same executable file for both platforms. A way to accomplish 

this is to explicitly link to a DLL using LoadLibrary, GetProcAddress, and FreeLibrary. 

You can then call the function as if it had been implicitly linked by the loader. 
LoadLibrary is prototyped as 


HINSTANCE LoadLibrary (LPCTSTR 1pLibFileName) ; 


The only parameter is the filename of the DLL. The system searches for DLLs in the 
following order: 


1. The image of the DLL that has already been loaded in memory. 
2. The statically linked DLL in ROM for a ROM-based executable. 
3. The file in the path specified in IpLibFileName parameter. 
4 


The directory of the executable loading the library. (This is supported only 
for Windows CE 2.1 and later.) 


5. The Windows directory. 
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6. The root directory. 
7. The image of the DLL in ROM. 


Notice in the search sequence above that if the DLL has already been loaded 
into memory, the system uses that copy of the DLL even if your pathname specifies 
a different file from the DLL originally loaded. Another peculiarity of LoadLibrary is 
that it ignores the extension of the DLL when comparing the library name to what’s 
already in memory. For example, if SIMPLE.dll is already loaded in memory and you 
attempt to load the control panel applet SIMPLE.cpl, which is under the covers sim- 
ply a DLL with a different extension, the system won’t load SIMPLE.cpl. Instead the 
system returns the handle to the previously loaded SIMPLE.dIl. 

LoadLibrary returns either an instance handle to the DLL that’s now loaded or 
O if for some reason the function couldn’t load the library. 

Once you have the DLL loaded, you get a pointer to a function exported by 
that DLL by using GetProcAddress, which is prototyped as 


FARPROC GetProcAddress (HMODULE hModule, LPCWSTR IpProcName) ; 


The two parameters are the handle of the module and the name of the function you 
want to get a pointer to. The function returns a pointer to the function or 0 if the 
function isn’t found. Once you have a pointer to a function, you can simply call 
the function as if the loader had implicitly linked it. 

When you are finished with the functions from a particular library, you need to 
call FreeLibrary, prototyped as 


BOOL FreeLibrary (HMODULE hLibModule); 


FreeLibrary decrements the use count on the DLL. If the use count drops to 0, the 
library is removed from memory. 

The following routine solves that same problem I presented earlier Chow to 
retrieve the SIP rectangle without using compile-time switches). The routine explic- 
itly loads the two possible functions, calls the one found, and frees the libraries loaded. 
A more efficient application would load the libraries and query the function pointers 
when the program was initialized instead of performing this task each time the func- 
tions were needed. 


// Type definitions for the function pointers. 
typedef HRESULT (CALLBACK* GETSIPINFOFUNC)(SIPINFO *); 
typedef HRESULT (CALLBACK* SHSIPINFOFUNC) (INT, INT, PVOID, INT); 


int MyGetSipRectl (RECT *prect) { 
HINSTANCE hCoreD11, hAGYShel1l; 
GETSIPINFOFUNC IpfnGetSipInfo; 
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SHSIPINFOFUNC lpfnSHSipInfo; 
SIPINFO si; 
INT re = @; 


//Load the DLL. 
hCoreDI1 = LoadLibrary(TEXT("cored11.d11")); 
// If we can't load Coredl1, something is really strange! 
if (!hCoreDl11) 
return -2; 


// Prepare structure for call. 
memset (&si, @, sizeof (si)); 
si.cbSize = sizeof (SIPINFO); 


// Attempt to get a pointer to GetSipInfo. 
lpfnGetSipInfo = (GETSIPINFOFUNC)GetProcAddress(hCoreD11, 
TEXT("GetSipInfo")); 
if (lpfnGetSipInfo) { 
// Call GetSipInfo. 
(*lpfnGetSipInfo)(&si); 


} else { 
// This DLL exports the Palm-size PC shell APIs. 
hAGYShel1= LoadLibrary(TEXT("aygshell.d11")); 
if (hAGYShel1) { 


// Attempt to get a pointer to SHSipInfo. 
TpfnSHSipInfo = (SHSIPINFOFUNC)GetProcAddress( 
hAGYShell, TEXT("SHSipInfo"™)); 
if (lpfnSHSipInfo) { 
(*lpfnSHSipInfo)(SPI_GETSIPINFO, 0, &si, @); 


} else 
re = -l; 
FreeLibrary (hAGYShel11); 
} else 
re = -l; 


} 
// At this point, one of the two functions has been called. 
it Eee) 

*prect = si.rcSipRect; 


// Free the library. 


FreeLibrary(hCoreD11); 
return rc; 
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This routine can be run on any platform, but will work only with those that export 
one of the two get SIP information functions. On the other platforms, the routine simply 
returns an error code of —1. 


Run-Time Version Checking 


When you’re determining the version of the Windows CE operating system at run 
time, you use the same function as under other versions of Windows—GetVersionEx, 
which fills in a OSVERSIONINFO structure defined as 


typedef struct _OSVERSIONINFO{ 
DWORD dwO0SVersionInfoSize; 
DWORD dwMajorVersion; 
DWORD dwMinorVersion; 
DWORD dwBuildNumber; 
DWORD dwPlatformld; 
TCHAR szCSDVersion[ 128 ]; 
} OSVERSIONINFO; 


Upon return from GetVersionEx, the major and minor version fields are filled 
with the Windows CE version. This means, of course, that you can’t simply copy 
desktop Windows code that branches on classic version numbers like 3.1 or 4.0. 
The dwPlatformld field contains the constant VER_PLATFORM_WIN32_CE under 
Windows CE. 

Although it’s possible to differentiate platforms by means of their unique Win- 
dows CE versions numbers, you shouldn’t. For example, you can identify the current 
Palm-size PC by its unique Windows CE version, 2.01, but newer versions of the Palm- 
size PC will be using different versions of Windows CE. Instead, you should call 
SystemParametersInfo with the SPIGETPLATFORMTYPE constant, as in 


TCHAR szPlat[256]; 
INT rc; 


rc = SystemParametersInfo (SPI_GETPLATFORMTYPE, sizeof (szPlat), 
szPlat, Q); 
if (Istrcemp (szPlat, TEXT ("Jupiter") == 0) { 
// Running on an H/PC Pro 
} else if (Istremp (szPlat, TEXT ("Palm PC") == @) { 
// Running on a Palm-size PC 
jj else if (Ilstremp (szPlat, TEXT ("HPC") == @) { 
// Running on an H/PC 
} 


Aside from the differences in their shells, though, the platform differences aren’t 
really that important. The base operating system is identical in all but some fringe 
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cases.> The best strategy for writing cross-platform Windows CE software is to avoid 
differentiating among the platforms at all—or at least as little as possible. 

For the most part, discrepancies among the user interfaces for the different 
consumer Windows CE devices can be illustrated by the issue of screen dimension. 
The Palm-size PC’s portrait-mode screen requires a completely different layout for 
most windows compared to the Handheld PC’s landscape-mode screen. The Handheld 
PC Pro’s screen is landscape, but it’s at least double the height of an H/PC screen. So, 
instead of looking at the platform type to determine what screen layout to use, you’d 
do better to simply check the screen dimensions using GetDeviceCaps. 

This has been a brief tour of some of the system issues for Windows CE. The 
configurability of Windows CE makes it the chameleon of operating systems, chang- 
ing its API and even its size, depending on the platform. Whatever the platform dif- 
ferences, though, remember that underneath the covers, all configurations of Windows 
CE share the same basic design. Keep this in mind as you look at the wide variety of 
platforms developed for Windows CE. 

The configurability of Windows CE makes it a powerful tool for the systems 
designer. Its Win32 API makes it familiar to thousands of programmers. But most of 
all, the Windows CE operating system is fun. Enjoy it. 


5. For example, first generation Palm-size PCs don’t support printing, so you wouldn’t want to im- 
plicitly link to any printing APIs if you wanted an application that ran on both the H/PC 2 and the 
original Palm-size PC. 
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COM Basics 


To qualify as COM compliant, all an object has to have is an implicit JUnknown in- 
terface. In C++ talk, a COM-compliant interface must be derived from, directly or 
indirectly, an JUnknown interface. The JUnknown interface has three methods: 
Querylnterface, AddRef, and Release. 

The methods AddRef and Release are called to increment and decrement the 
reference count of the COM interface. When an object is created and a pointer is 
returned by the object to an interface, an implicit call is made to Addkef. When a 
program no longer needs an interface, it calls Release, which decrements the use count 
for that interface. When the use count for all interfaces exposed by the object is 0, 
Release deletes the object. 

The third method, QueryInterface, provides a way for the caller to receive a 
pointer to a specific interface the COM-compliant object supports. Querylnterface is 
prototyped as 


HRESULT QueryInterface (REFIID iid, void ** ppvObject); 


The first parameter to QueryInterface is an identifier to an interface that the caller 
is requesting. Because there are countless interfaces and new ones generated every 
day, this identifier needs to be unique—globally and universally unique—for all COM 
interfaces ever programmed. Thus, the globally unique interface identifier is abbre- 
viated as a GUID, pronounced goo-id or gwid (rhymes with squid). If you create your 
own unique interface, you too will need a GUID. You can create your own GUID using 
the GUIDGEN utility provided with Visual C++. 

The second parameter is a pointer that receives a pointer to the requested in- 
terface. So, to use an interface, the QueryInterface method, which must be included 
in any COM-compliant interface, is called to return a pointer to a specific interface 
exposed by the object. If the object makes a requested interface available, a pointer 
to that interface is returned. 
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USING COM INTERFACES 


In many cases, applications use COM interfaces without even knowing that’s what 
they’re doing. In the RAPI stream example I used in Chapter 11, both the CE-side and 
the PC-side applications used an Stream interface. This interface is formally defined 
as a COM interface, but because the pointer to the interface was provided, neither 
the CE- nor the PC-side applications had to know anything about COM. 


COM CLIENTS 
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However, sometimes you need to directly create and use a COM interface. In this case, 
the application becomes a COM client. Before an application can use the COM li- 
brary, it must initialize the COM handler library by calling this function: 


HRESULT CoInitialize (LPVOID pvReserved); 


The only parameter is reserved and must be set to NULL. Colnitialize returns S_OK 

if the COM library was successfully initialized. You can also call ColnitializeEx in- 

stead of Colnitialize if you need to more precisely specify how the library is initialized. 
To get a pointer to an interface, you then call the function 


STDAPI CoCreateInstance (REFCLSID rclsid, LPUNKNOWN pUnkOuter, 
DWORD dwClsContext, REFIID riid, 
LPVOID * ppv); 


The first parameter for this function is the class identifier of the interface or object 
you're trying to load. The second parameter specifies a pointer to an JUnknown 
interface if you’re trying to extend an existing COM object with the new interface. 
In all our uses of this function, this parameter will be NULL. The third parameter 
is the context in which you’re opening the object. For our purposes, we’ll use 
CLSCTX_SERVER, indicating that we’re loading a server object and we don’t care 
whether that server runs in our process or in another process. The riid parameter 
specifies the interface ID of the interface to be loaded. Finally, the last parameter, 
ppv, is a pointer to a value that will receive the pointer for the interface being re- 
quested. CoCreateInstance returns S_OK if the function was successful. 

At this point, the client has a pointer to the interface for the object and can call 
the methods provided by that interface. When you’re finished with the object, a call 
should be made to the Release method of the object to free it. 
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COM SERVERS 


On the other side of the COM fence is a COM server. A COM server is a module, EXE 
or DLL, which provides one or more COM interfaces. There are three types of COM 
servers: in-proc, which operate in the process space of the caller; local, which oper- 
ate in separate process spaces; and remote, which reside on different machines from 
the COM clients. For all our cases, I'll stick to COM in-proc servers. 

A COM server doesn’t just provide a pointer to a requested interface. That would 
be too easy. Instead, a COM server must make available an additional interface, 
IClassFactory. IClassFactory is composed of the JUnknown methods, Querylnterface, 
AddRef, and Release along with two additional methods, CreateInstance and Lock- 
Server. It’s through calling methods within [ClassFactory that the server creates other 
objects provided by the server. To create an instance of an interface, the client calls 
the [ClassFactory CreateInstance method. The prototype for this function is 


HRESULT CreateInstance (IUnknown * pUnkOuter, REFIID riid, 
void ** ppvObject); 


If the first parameter isn’t NULL, it’s a pointer to the controlling JUnknown in- 
terface of the aggregate object. The second parameter is the CLSID for the object you 
want to create. Finally, the ppvObject parameter points to a value that receives a pointer 
to the interface provided by the newly created object. When CreateInstance is called, 
IClassFactory examines the GUID in the riid parameter to see what interface it iden- 
tifies; if that interface is provided, /ClassFactory creates the object that implements 
the interface and queries that object for a pointer to the newly created interface that 
it then returns. 

So, just how does a client get access to [ClassFactory? Well, if we’re talking 
about in-proc servers, COM must fall back on functions exported from the DLL or 
EXE. A COM server must provide at least two exported functions—DllGetClassObject 
and DilCanUnloadNow. The first of these two functions is the more interesting. It’s 
prototyped as 


STDAPI D11GetClassObject (REFCLSID rclsid, REFIID riid, 
LPVOID *ppv); 


The first parameter is a class ID, which is a GUID that uniquely identifies this object. 
Many objects, for example, might export a file filter interface, but each will have a 
unique class ID. The COM server must ensure that the object’s class ID matches its 
class ID and, if not, return an error to the caller. 

The second parameter is the reference ID for the interface that the client wants. 
When calling DilGetClassObject, the reference ID usually identifies either JUnknown 
or IClassFactory, but it doesn’t have to. The server’s responsibility here is to compare 
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the requested interface with those that are provided. If that interface is provided, a 
pointer to it is returned in a variable pointed to by the third parameter, ppv. 
The other exported function is 


STDAPI D11CanUnloadNow (void); 


This function is called to determine whether the DLL can be removed from memory. 
The COM server is required to know whether any object instances are currently ac- 
tive. Each object tracks this information by keeping a count of the number of instances 
of itself currently created. This is what the AddRefand Release methods of JUnknown 
are used for. When the use count for a specific object/interface reaches 0, the Release 
method of the object deletes the object. The server must keep track of which objects 
are still in use and return S_FALSE from DilCanUnloadNow if any of the objects it 
serves are still in use. 

One final point. Plenty of DLLs are in a system. How does the COM library know 
to load a specific DLL to look for a specific class? It looks in the registry. If you look 
in the registry under [HKEY_CLASSES_ROOTI]\CLSID, you'll see hundreds of keys with 
class IDs for names. Each of these class ID keys has a series of subkeys that identify 
the DLL that implements that COM object as well as identifying other information im- 
portant to the implementation of the server. 

So, to sum up, when a client requests an object identified by a class ID, the COM 
library finds the name of the DLL that implements that object in the registry. The DLL 
is then loaded into memory and the exported function DilGetClassObject is called to 
confirm the class ID and to (usually) request a pointer to the object’s associated 
IClassFactory object. The client then calls a method in the /ClassFactory interface to 
request that an object that has a requested interface be created. If it can comply, the 
IClassFactory object creates the requested object and returns a pointer to an inter- 
face exposed by that object. Whew. 

This short and almost trivial COM primer isn’t meant to turn you into a COM 
expert. My goal is to help you identify all those extra functions implemented in the 
examples that use COM in this book. I strongly encourage you to learn more about 
COM from other books and papers. For all its complexity, COM is the wave of the 
present and future in Windows programming. 
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Special Characters 
& (ampersand), 129, 175 
* (asterisk), 173, 413 

: (colon), 541, 546 

... (ellipsis), 129 

/ forward slash), 128 

? (question mark), 413 


A 
ACCELERATORS resource type, 129 
accept function, 601, 603-4 
access rights, 356-57, 363-65, 409 
ACM (audio compression manager) device 
drivers, 540 
ActionFlags field, 727, 728 
Active Desktop, 709, 749 
Address field, 629 
Advanced Windows (Richter), 377 
AF_IRDA constant, 602, 603 
AF_NET constant, 602 
AlbumDB program, 435-67 
AlbumDB.c, 441-65 
AlbumDB.h, 438-41 
AlbumDB.rc, 436—48 
window, 436 
AllocationBase field, 363, 364 
ampersand (&), 129, 175 
annunciators, 716-18 
API (application programming interface). See 
also RAPI (Windows CE Remote API) 
Clipboard API, 793 
database API, 379, 417-67 _ 
file API, 379-417 
functions, availability of, on particular 
platforms, 5 


API (application programming interface), 
continued 
functions, Hungarian notation and, 15 
heap API, 358-59, 367-69 
IME API, 756 
Notification API, 710, 753, 680, 804 
registry API, 379, 467-91 
socket API (WinSock), 599-626 
virtual memory, 354, 361 
applications. See also API (application 
programming interface) 
cross-platform, 802-9 
launch keys for, 788-92 
Apply button, 218 
Appointments database, 421 
ASCII (American Standard Code for Informa- 
tion Interchange) 
IrSock and, 629 
resource files, 128—29 
strings, 20 
Unicode vs., 4, 600 
asterisk (*), 173, 413 
ATA flash cards, 380 
atoms 
basic description of, 23 
exclusion of, from fields, 23 
Auto PC, 5, 803-4 


B 

background 
color, 62, 40-47, 207, 298 (see also color) 
mode, 40 

backward compatibility, 35 

bar graphs, 74 

baselines, for text, 51 

batteries, 501—2, 350, 801—2 

Baudkate field, 549, 553 

baud rates, 549-50, 553 
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BEGIN keyword, 129, 210 
BeginPaint function, 29-30, 37, 38, 61 
bEnable flag, 95 

bErase parameter, 37 

biBitCount field, 67 
biclrImportant field, 67 
biclrUsed parameter, 67 
biCompression field, 67 

binary data blocks, defining, 129 
bind function, 601, 604 
bInheritHandle parameter, 498 
bInitialOwner parameter, 513 
bInitialState parameter, 508 


BIOS (basic input/output system), 350, 501 


biPlanes field, 67 
biSizelmage parameter, 67 
BitBit function, 69, 70 
BITMAPINFOHEADER structure, 66-67 
BITMAPINFO structure, 66, 74 
bitmaps, 129, 130, 132. See also images 
as arrays of bits, 63, 64 
basic description of, 63-70 
brushes and, 73-74 
for command bar buttons, 270, 271 
referencing, 271-73 
representing the IM control, 764 
bits, bitmaps as arrays of, 63, 64 
BITSPIXEL value, 40 
biWidth field, 67 
biXPelsPerMeter field, 67 
biYPelsPerMeter field, 67 
bLastMove field, 147 
block mode, 648 
blocks 
__try block, 531 
__try, __except block, 532-34 
__try, _ finally block, 531, 534-36 
_bManualReset parameter, 508 
BN_CLICKED message, 170, 171, 206 
boilerplate code, 14 


Bold button, position of, on the command 


bar, 280 
Boolean data type, 168, 417 
boot process, 540, 794-801, 802 
breakpoints, setting, 19 
brushes, 73-75, 76, 77-86 
BS_2STATE style flag, 171 
BS_AUTO2STATE style flag, 171. 
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BS_AUTOSSTATE style flag, 206 
BS_AUTOCHECKBOX style flag, 171, 206 


BS_AUTORADIOBUTTON style flag, 171, 206 


BS_BOTTOM style flag, 171 
BS_CHECKBOxX« style flag, 171 
BS_ICON style flag, 172 
BS_LEFT style flag, 171 
BS_MULTILINE style flag, 171 
BS_OWNERDRAW style flag, 172 
BS_RADIOBUTTON style flag, 171 
BS_RIGHT style flag, 171 
BS_TOP style flag, 171 
BtnDlg.c, 244-50 
BtnWnd.c, 186-92, 206 
BtnWndProc procedure, 206-7 
buf parameter, 604 
Button control class, 170-73 
buttons. See also buttons Cisted by name) 
background color for, 207 
bitmaps for, 270, 271 
customizing the appearance of, 171-73 
disabled, 274-75 
drop-down, 275-77 
position of, on the command bar, 280 
buttons (listed by name). See also buttons; 
Close button 
Apply button, 218 
Bold button, 280 
Cancel button, 218 
Help button, 210, 268, 279 
IDCANCEL button, 214-16, 223 
IDOK button, 214-16, 223 
Italic button, 280 
New button, 280 
Notify button, 726 
OK button, 218, 223, 583, 584 
Open button, 280 
Print button, 280 
Save button, 280 
Send button, 518, 529 
Start button, 63, 149, 709 
Underline button, 280 
bWaitAll parameter, 511 
BY_HANDLE_FILE_INFORMATION 
structure, 388-89 
bytes 
layout of, within a bitmap, 64, 65 
multiple, storage of characters in, 5—6 
ByteSize field, 551 


C 
C programming, 26, 370, 742-43 
C++ programming, 370 
CALBACK type definition, 26 
Calc program, 497, 715-16, 800, 8O1 
calc.exe, 497, 716 
calendar control, 5 
callback functions, handling fonts with, 
52-53, 61-62 
Cancel button, 218 
Casio Handheld PC, 796. See also H/PC 
(Handheld PC) 
catch keyword, 531 
Categories database, 421 
cbInQue field, 556 
cbOutQue field, 556 
cbSize field, 168, 169, 297, 751 
cbStructure field, 584 
cbWndExtra field, 22, 152 
CCS_VERT style flag, 295 
cDayState field, 321 
CeChat program, 560-77 
CeChat.c, 564-76 
CeChat.h, 562-64 
CeChat.rc, 561-62 
window, 561 
CeCheckPassword function, 638 
CeCloseHandle function, 638 
CeCopyFile function, 639 
CeCreateDatabaseEx function, 421, 423, 429, 
435, 641 
CeCreateDatabase function, 418, 421, 423, 
634, 641 
CeCreateDirectory function, 639 
CeCreateFile function, 638 
CeCreateProcess function, 638 
CeDatabaseEx function, 433 
CeDatabaseSeek function, 429 
CEDB_ALLOWREALLOC flag, 430 
CEDBASEINFO structure, 423, 429, 435 
CEDB_AUTOINCREMENT flag, 424 
CEDB_MAXPROPDATASIZE flag, 418 
CEDB_MAXRECORDSIZE flag, 418 
CEDB_PROPDELETE flag, 432 
CEDB_PROPNOTFOUND flag, 431 
CEDB_SEEK_BEGINNING flag, 427 
CEDB_SEEK_CEOID flag, 427 
CEDB_SEEK_CURRENT flag, 427 


Index 


CEDB_SEEK_END flag, 427 
CEDB_SEEK_VALUEFIRSTEQUAL flag, 427 
CEDB_SEEK_VALUEGREATER flag, 427 
CEDB_SEEK_VALUENEXTEQUAL flag, 427 
CEDB_SEEK_VALUESMALLER flag, 427 
CEDB_SORT_CASEINSENSITIVE flag, 422 
CEDB_SORT_DESCENDING flag, 422 
CEDB_SORT_UNKNOWNFIRST flag, 422 
CEDB_VALIDCREATE flag, 423 
CEDB_VALIDDBFLAGS flag, 423 
CEDB_VALIDMODTIME flag, 423 
CEDB_VALIDNAME flag, 423 
CEDB_VALIDSORTSPEC flag, 423 
CEDB_VALIDTYPE flag, 423 
CeDeleteDatabaseEx function, 641 
CeDeleteDatabase function, 641 
CeDeleteFile function, 639 
CeDeleteRecord function, 641 
CeEnumDBVolumes function, 420 
CEFILEINFO structure, 434-35 
CeFindAllDatabases function, 642, 643 
CeFindAllFiles function, 638, 642, 643, 648 
CeFindClose function, 638 
CE_FIND_DATA structure, 640-41, 648 
CeFindFirstDatabaseEx function, 641 
CeFindFirstDatabase function, 433, 641 
CeFindFirstFile function, 638 
CeFindNextDatabaseEx function, 641 
CeFindNextDatabase function, 433, 641 
CeFindNextFile function, 638 
CEFind program, 743-47 

CEFind.c, 744-47 

window, 743 
CeGetDesktopDeviceCaps function, 638 
CeGetFileAttributes function, 638 
CeGetFileSize function, 639 
CeGetFileTime function, 639 
CeGetStoreInformation function, 634, 637, 638 
CeGetSystemInfo function, 638 
CeGetSystemMetrics function, 638 
CeGetSystemPowerStatusEx function, 638 
CeGetVersionEx function, 635, 638 
CeGlobalMemoryStatus function, 638 
CEIODINFO structure, 434 
CeMoundDBVol function, 419-20, 642 
CeMoveFile function, 639 
CENOTIFICATION structure, 425, 426 
CENOTIFYREQUEST structure, 425, 426 
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CeOidGetInfoEx function, 641 
CeOidGetInfo function, 641 
CeOpenDatabaseEx function, 425, 641 
CeOpenDatabase function, 425, 641 
CEPROPID structure, 430, 432 
CEPROPVAL structure, 427, 432 
CeRapiFreeBuffer function, 643 
CeRapiGetError function, 637 
CeRapilnitEx function, 636, 647 
CeRapilnit function, 636, 648, 662 
CeRapiInvoke function, 648-49, 651-53, 662 
CeRapiUninit function, 636 
CeReadFile function, 638 
CeReadkecordPropsEx function, 430, 431, 
432, 641 
CeReadkRecordProps function, 430, 431, 641, 
643, 405 
CeRemoveDirectory function, 639 
CeRunAppAtEvent function, 680 
CeSeekDatabase function, 428, 641 
CeSetDatabaselnfo function, 422, 435 
CeSetDatabaseInfoEx function, 641 
CeSetEndOfFile function, 638 
CeSetFilePointer function, 638 
CeSetFileTime function, 639 
CeSetUserNotification function, 726-28 
CESH, 796 
CESVC_CUSTOM_MENUS registry key, 663 
CESVC_DEVICE_SELECTED registry key, 664 
CESVC_DEVICES registry key, 663, 664 
CESVC_DEVICEX registry key, 664 
CESVC_FILTERS registry key, 663, 664 
CeSucOpen function, 664, 665, 667-68, 684 
CESVC_ROOT_MACHINE registry key, 
6063, 668 
CESVC_ROOT_USER registry key, 663 
CESVC_SERVICES_COMMON registry 
key, 663 
CESVC_SERVICES_USER registry key, 664 
CESVC_SYNC_COMMON registry key, 663 
CESVC_SYNC registry key, 664 
CeUnmountDBVol function, 420, 642 
CeUtil functions, 662-67, 681, 684 
CEVT_LPWSTR constant, 422 
CeWriteFile function, 638 
CeWriteRecordProps function, 432, 641 
cFindData parameter, 642 
char data type, 5, 15 
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chat program, 560-77 
check boxes 
background color for, 207 
basic description of, 170-71 
child windows, 6, 149 
basic description of, 150-69 
enumerating, 151 
finding, 151, 152 
Choose Color dialog box, 224 
Choose Font dialog box, 224 
circles, drawing, 75-76 
cleanup action, 21 
ClearCommBreak function, 554—55 
ClearCommeError function, 556 
ClientWnd.c, 154, 159-68 
Clipboard API, 793 
clipping regions, 37, 62 
Close button, 19, 223, 268, 374 
adding, 28 
disabling, 22 
Windows logo on, 63 
CloseFile function, 382 
clrBack field, 298 
CLRBREAK flag, 555 
CLRDTR flag, 555 
CLRIR flag, 555 
CLRRTS flag, 555 
CmdBand program, 304-19 
CmdBand.c, 307-18 
CmdBand.h, 305-7 
CmdBand.rc, 304—5 
CMDBAR_HELP flag, 279 
CMDBAR_OK flag, 279 
CmdBar program, 280-94 
CmdBar.c, 283-94 
CmdBar.h, 281-83 
CmdBar.rc, 280-81 
CMD.EXE, 743 
CnctNote program, 671-80 
CnctNote.cpp, 673-80 
CnctNote.h, 672—73 
CnctNote.rc, 671-72 
colon (:), 541, 546 
color 
background, 62, 40-47, 207, 298 
for bitmaps, 67-68 
for buttons, 172-73 
for controls, 207, 298, 320 


color, continued 
foreground, 40-47 
palettes, specifying the number of colors 
in, 67-68 
RGB, 66-68, 72-74, 172-73 
transparent, 70 
Color dialog box, 150, 261 
COLOR_STATIC constant, 207 
COM (Component Object Model), 546, 553— 
54, 558, 576 
basic description of, 705 
input methods and, 753-54, 758-59 
method of connection notification, 669-80 
objects, file filters as, 680-706 
shell programming and, 710, 715, 747, 
753-54, 758, 759 
combo boxes, 170, 174, 277-78 
Combo control class, 170, 174 
COM device drivers, 540, 544 
command band control 
basic description of, 294-319 
adding, 296-300 
CmdBand program for, 304-19 
configuring, 300-301 
creating, 295-96 
destroying, 318 
image lists for, 296 
layout, saving, 301-3 
messages, handing, 303 
COMMANDBANDRESTOREINFO structure, 
301-3 
CommandBar_AddAdornments function, 
28, 279 
CommandBar_AddBitmap function, 270, 
271-72, 274 
command bar control 
basic description of, 5, 268-80 
CmdBar program for, 280-94 
creating, 28, 268 
design guidelines for, 279-80 
destroying, 30-31, 279 
positioning the scroll bar relative to, 63 
CommandBar_Create function, 28 
CommandBar_Destroy function, 30-31 
CommandBar_DrawMenubar function, 269 
CommandBar_Height function, 29, 279 
CommandBar_InsertComboBox function, 278 
CommandBar_InsertMenubar function, 269 
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commcetrl.h, 14, 267, 271 

COMMCTRL image, 357 

COMMPROP structure, 553 

COMMTIMEOUTS structure, 551, 552 

Compact Flash Cards, 381, 540, 542 

compatibility, backward, 35 

compile-time versioning, 804-5 

ComposeLine function, 407 

compression, file, 67, 381, 386-87 

COMSTAT structure, 556 

CON (console) device drivers, 540, 742-43 

CONNECTDLGSTRUCT structure, 583 

connect function, 601, 612 

console applications, 540, 742-47 

constants 
AF_IRDA constant, 602, 603 
AF_NET constant, 602 
CEVT_LPWSTR constant, 422 
COLOR_STATIC constant, 207 
CSIDL_BITBUCKET constant, 712 
CSIDL_DESKTOP constant, 712 
CSIDL_DRIVES constant, 712 
CSIDL_FAVORITES constant, 712 
CSIDL_FONTS constant, 712 
CSIDL_PERSONAL constant, 712 
CSIDL_PROGRAMS constant, 712, 715 
CSIDL_RECENT constant, 712 
CSIDL_STARTMENU constant, 712 
CSIDL_STARTUP constant, 712 
EVENTPARITY constant, 551 
NOPARITY constant, 551 
ODDPARITY constant, 551 
PROCESSOR_ARCHITECTURE_INTEL 

constant, 354 
PROCESSOR_ARCHITECTURE_SHx 
constant, 354 

PROCESSOR_HITACHI_SH4 constant, 354 
PROCESSOR_HITACHI_SH3 constant, 354 
SPACEPARITY constant, 551 
STILL_ACTIVE constant, 497 
VK_0-VK_9 constants, 90 
VK_A-VK_Z constants, 90 
VK_ADD constant, 91 
VK_APOSTROPHE constants, 91 
VK_APPS constant, 91 
VK_ATIN constant, 92 
VK_BACK constant, 89 
VK_BACKQUOTE constant, 91 
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VK_BACKSLASH constant, 91 
VK_CANCEL constant, 89 
VK_CAPITAL constant, 90 
VK_CLEAR constant, 89 
VK_COMMA constant, 91 
VK_CONTROL constant, 90 
VK_CRSEL constant, 92 
VK_DECIMAL constant, 91 
VK_DELETE constant, 90 
VK_DIVIDE constant, 91 
VK_DOWN constant, 90 
VK_END constant, 90 
VK_EQUAL constant, 91 
VK_EREOF constant, 92 
VK_ESCAPE constant, 90 
VK_EXECUTE constant, 90 
VK_EXESEL constant, 92 
VK_F1—-VK_F24 constants, 91 
VK_HELP constant, 90 
VK_HOME constant, 90 
VK_HYPHEN constant, 91 
VK_INSERT constant, 90 
VK_LBRACKET constant, 91 
VK_LBUTTON constant, 89, 94 
VK_LCONTROL constant, 91 
VK_LEFT constant, 90 
VK_LMENU constant, 91 
VK_LSHIFT constant, 91 
VK_LWIN constant, 90, 788 
VK_MENU constant, 90, 94 
VK_MULTIPLY constant, 91 
VK_NEXT constant, 90 
VK_NONAME constant, 92 
VK_NUMLOCK constant, 91 
VK_NUMPAD0O-9 constants, 91 
VK_OEM_CLEAR constant, 92 
VK_OFF constant, 92 
VK_PA1 constant, 92 
VK_PERIOD constant, 91 
VK_PLAY constant, 92 
VK_PRIOR constant, 90 
VK_RBRACKET constant, 91 
VK_RBUTTON constant, 89 
VK_RCONTROL constant, 91 
VK_RETURN constant, 90 
VK_RIGHT constant, 90 
VK_RMENU constant, 91 
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VK_RSHIFT constant, 91 
VK_SCROLL constant, 91 
VK_SELECT constant, 90 
VK_SEMICOLON constant, 91 
VK_SEPARATOR constant, 91 
VK_SHIFT constant, 90 
VK_SLASH constant, 91 
VK_SNAPSHOT constant, 90 
VK_SPACE constant, 90 
VK_SUBTRACT constant, 91 
VK_TAB constant, 89 
VK_UP constant, 90 
VK_ZONE constant, 92 
const keyword, 372 
Contacts database, 421 
CONTROL keyword, 131, 210-11 
controls. See also specific controls 
basic description of, 149-50, 169-207 
common, 265-337 
new, in Windows CE, 5 
Cool Bars, 268 
CopyFile function, 412 
Coredll.dll, 357, 358, 802, 805 
cPlanes parameter, 64 
cPropID parameter, 432 
CPUs (central processing units), 794, 801 
exception handling and, 534 
memory management and, 351-52, 354, 
356, 365, 373-74 
that support Windows CE, 3 
system programming and, 793-94, 801 
target, selecting, 16 
threads and, 499, 501 
crColor parameter, 72, 73 
CreateBitmap function, 67 
CreateCommandBand routine, 318 
CreateCompatibleDC function, 70 
CreateDialog function, 218 
CreateDIBPatternBrushPt function, 74, 85 
CreateDIBSection function, 67, 68 
CreateDirectory function, 412 
CreateEvent function, 508, 509 
CreateFileForMapping function, 408 


CreateFile function, 382-84, 387, 407-8, 419, 
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CreateFileMapping function, 409, 410-12, 529 


CreateFontIndirect function, 49 


CreateHatchBrush function, 85 
CreateMenu function, 126 
CreateMessage function, 217 
CreatePenIndirect function, 72-73 
CreateProcess function, 494-97, 502 
CREATESTRUCT structure, 125 
CreateThread function, 502, 503 
CreateWindowEx function, 170, 324 
CreateWindow function, 24, 25, 27, 150, 165, 
170, 206, 324 

critical sections, 514—15 
CRITICAL_SECTION structure, 514 
cross-platform applications, 802-9 
CSIDL_BITBUCKET constant, 712 
CSIDL_DESKTOP constant, 712 
CSIDL_DRIVES constant, 712 
CSIDL_FAVORITES constant, 712 
CSIDL_FONTS constant, 712 
CSIDL_PERSONAL constant, 712 
CSIDL_PROGRAMS constant, 712, 715 
CSIDL_RECENT constant, 712 
CSIDL_STARTMENU constant, 712 
CSIDL_STARTUP constant, 712 
CUD field, 172 
CtlType field, 172 
CtlView program, 176-208, 261 

CtlView.c, 180-86, 206 

CtlView.h, 176-80 

CtlView.rc, 176 

windows, with the button child window 

displayed, 206 

CTS (Clear to Send) signals, 547, 556 
CW_USEDEFAULT flag, 24 
cxIdeal field, 298 
cxMinChild field, 298 
cyMinChild field, 298 


D 

databases 
AlbumDB program for, 435-67 
API for, 379, 417-67 
communicating with, 518 
creating, 421-24 
deleting, 432—33 
designing, 418 
desktop connectivity and, 641-43 
enumerating, 433-34 
management functions for, 641-43 
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databases, continued 
opening, 424-26 
types of, predefined, 427 
volumes, 418-20, 465-67 
data compression, 67, 381, 386-87 
data types 
Boolean data type, 168, 477 
double data type, 15, 64, 417 
integer data type, 15, 417 
the registry API and, 467, 471 
supported by Windows CE, summary 
of, 417 
date and time picker control, 5, 321-24 
DB_CEOID_CHANGED message, 424-25 
DB_CEOID_CREATED message, 424—26 
DB_CEOID_RECORD_DELETED message, 
424—25 
DCs (device contexts) 
basic description of, 29, 37-47, 64-70 
bitmaps and, 64-65, 66, 68-70 
deleting, 70 
fonts and, 49-50, 53 
KeyTrac program and, 104-5 
returning handles to, 61 
the Windows CE file API and, 407 
DCX_LOCKWINDOWUPDATE flag, 38 
DCX_NORESETATTRS flag, 38 
DCX_PARENTCLIP flag, 38 
DCX_VALIDATE flag, 38 
DDBs (device dependent bitmaps), 65-66. 
See also bitmaps 
DDI.DLL, 540 
debugging, 18-19, 371. See also errors 
booting and, 797-98 
processes and, 495, 517 
Debug tab, 18 
DEF (function definition) files, 651, 693 
DefWindowProc function, 26, 32, 208, 213 
DeleteDC function, 70 
DeleteFile function, 412, 413 
DeleteObject function, 62 
deleting 
databases, 432~—33 
device contexts (DCs), 70 
directories, 412 
files, 412, 413 
properties, 432-33 
records, 432-33 
registry values, 471-72 
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Depend20 line, 798 
Deselect method, 759, 763 
desktop 
basic description of, 6 
connectivity, 633-705 
registry management functions, 643 
window management functions, 644-45 
DestroyCommandBand function, 318 
device contexts (DCs) 
basic description of, 29, 37-47, 64-70 
bitmaps and, 64-65, 66, 68-70 
deleting, 70 
fonts and, 49-50, 53 
KeyTrac program and, 104—5 
returning handles to, 61 
the Windows CE file API and, 407 
device dependent bitmaps (DDBs), 65-66. See 
also bitmaps 
device drivers. See also serial communications 
active, 540-43 
boot process and, 798-800 
console applications and, 742—43 
creating lists of, 542-43 
loading, 540, 541 
names of, 540, 541, 542 
native, 800 
querying the capabilities of, 553-54 
reading, 544—45 
three-letter prefixes for, 540, 541 
writing, 544-45 
DEVICE.EXE, 493, 540, 798-800, 802 
device independent bitmaps (DIBs), 65, 
66-68, 74. See also bitmaps 
device I/O control GOCTL) functions, 
544-45, 548 
IOCTL_CLR_DTR function, 544—45 
IOCTLI_CLR_RTS function, 544—45 
IOCTL_DISABLE_IR function, 544-45 
IOCTIL_GET_COMMSTATUS function, 
544-45 
IOCTL_GET_DCB function, 544-45 
IOCTL_GET_MODEMSTATUS function, 
544-45 
IOCTL_GET_PROPERTIES function, 544-45 
IOCTL_GET_TIMEOUTS function, 544—45 
IOCTL_GET_WAIT_MASK function, 544—45 
IOCTL_IMMEDIATE_CHAR function, 544-45 
IOCTL_PURGE function, 544—45 
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device I/O control COCTL) functions, 
continued 
IOCTL_SERIAL_ENABLE_IR function, 
544-45 
IOCTL_SET_BREAK_OFF function, 544—45 
IOCTL_SET_BREAK_ON function, 544-45 
IOCTL_SET_DCS function, 544-45 
IOCTL_SET_DTR function, 544-45 
IOCTL_SET_QUEUE_SIZE function, 544-45 
IOCTL_SET_RTS function, 544—45 
JOCTL_SET_TIMEMOUTS function, 544-45 
IOCTL_SET_WAIT_MASK function, 544—45 
IOCTL_SET_XOFF function, 544-45 
IOCTL_SET_XON function, 544-45 
IOCTL_WAIT_ON_MASK function, 544—45 
DEVICELIST structure, 606 
dialog boxes, 149-50, 224-61. See also dialog 
boxes Cisted by name) 
creating, 212-13 
default, 208 
DlgDemo program for, 226-61 
measuring, with dialog units, 209 
modal, 208, 217-18 
modeless, 208, 216-18 
procedures for, 213-16 
templates for, 129, 209-10, 214-16 
dialog boxes (listed by name). See also dialog 
boxes 
Choose Color dialog box, 224 
Choose Font dialog box, 224 
Color dialog box, 150, 261 
File Open dialog box, 150, 208, 224, 
225, 581 
File Save dialog box, 150 
Find dialog box, 208, 224 
Out Of Memory dialog box, 376, 725, 726 
Page Setup dialog box, 224 
Print dialog box, 150, 208, 224, 261 
Project Settings dialog box, 18 
Save As dialog box, 224 
DIALOG keyword, 209 
Dialog Manager, 208, 223-24 
DIALOG resource type, 129 
DIBs (device independent bitmaps), 65, 
66-68, 74. See also bitmaps 
directories. See also folders 
basic description of, 711 
computing the total size of files in, 414 


directories, continued 
creating, 412 
current, 380 
deleting, 412 
determining drives from, 415—17 
root, 380 
discardable keyword, 129, 209 
DispatchMessage function, 21, 132, 213, 217 
DivFile program, 691-705 
DivFile.cpp, 693, 696-704 
DivFile.h, 693—96 
DivFile.rc, 693-94 
DivFile.reg, 692-93 
div instruction, 533 
DlgDemo program, 226-61 
DlgDemo.c, 232-44 
DilgDemo.h, 229-32 
DlgDemo.rc, 227-29 
StaticDlg.c, 255-57 
window, 226 
DLGTEMPLATE structure, 212 
DilMain function, 767 
DLLs (dynamic-link libraries), 127, 517, 
380, 506 
common controls and, 265, 267, 268, 270 
desktop connectivity and, 633, 635, 648-52, 
663, 667, 682, 693 
device drivers as, 540, 541 
explicit linking and, 805, 806 
initializing, 599-600 
memory management and, 358, 369, 372 
system programming and, 799-800, 802, 
805, 806 
DMA (direct memory access), 361 
DoActivateMain procedure, 31-32 
DOC file type, 681-83 
DoCreateBtnWind function, 206 
DoCreateMain function, 27-28, 405 
DoDestroyMain function, 32 
DoHibernateMain procedure, 30—31 
DoMainCommandcColor function, 261 
DoMainCommandPrint function, 261 
DoMainCommandVCmdBand routine, 318 
DoMainCommandVCombo routine, 294 
DoMainCommandvVStd routine, 294 
DoMainCommandVView routine, 294 
DoMouseMain routine, 107 
DoOpenViewer routine, 407 


Index 


DoPaintClient function, 166 
DoPaintSip routine, 787 
Do prefix, 27 
DOS (Disk Operating System), 6, 47, 351, 382 
drive letters, 415 
serial communications and, 545, 550 
truncating files in, 386 
dot format, 629 
double data type, 15, 64, 417 
double-taps, 106 
downloading, newly compiled files, 18-19 
DrawBoard routine, 123 
drawing mode, 40, 46 
DRAWITEMSTRUCT structure, 172 
DrawMenuBar function, 269 
DrawText function, 30, 33, 35, 39, 46, 51, 
61-62 
drives 
determining, from directories, 415-17 
letters for, 380, 415 
mapping remote, 581-83 
DS_ABSALIGN style flag, 209 
DS_CENTER style flag, 209 
DS_MODALFRAME style flag, 209 
DSR (Data Set Ready) signal, 556 
DS_SETFONT style flag, 210 
DS_SETFOREGROUND style flag, 210 


-‘DTN_FORMAT message, 324 


DTN_FORMATQUERY message, 324 
DTN_USERSTRING message, 322 
DTN_WMKEYDOWN message, 324 

DTR (Data Terminal Ready) line, 550 
DTR_CONTROL_DISABLE flag, 550 
DTR_CONTROL_ENABLE flag, 550 
DTR_CONTROL_HANDSHAKE flag, 550 
DTS_APPCANPARSE style flag, 322 
DTS_IC_DATE_CLASSES style flag, 322 
DTS_LONGDATEFORMAT style flag, 322 
DTS_SHORTDATEFORMAT style flag, 322 
DTS_SHOWNONE style flag, 322 
DTS_TIMEFORMAT style flag, 322 
DTS_UPDOWN style flag, 322 

Duncan, Ray, 16 

DuplicateHandle function, 516 
dwAllocationGranularity field, 354 
dwAvailPageFile field, 355, 356 
dwAvailPhys field, 355 

dwAvailVirtual field, 355 
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dwCreateFlags parameter, 495, 502 
dwCurrentRxQueue field, 554 
dwCurrentTxQueue field, 554 
dwDatabaseType parameter, 433 
dwDbaseType field, 423 
dwbDesiredAccess parameter, 382, 408 
dwDevNum field, 583 
dwFreeType parameter, 362 
dwiIndex parameter, 472 
dwinfoLevel parameter, 590 
dwinitialSize parameter, 368 
dwloControlCode parameter, 544 
dwLength field, 355 
dwMaxBaud field, 553 
dwMaxkxQueue field, 554 
dwMaxTxQueue field, 554 
dwMemoryLoad field, 355 
dwMilliseconds parameter, 504, 509 
dwMoveMethod parameter, 385 
dwNumberOfBytesToMap parameter, 409 
dwOffset parameter, 68 
dwoOlD field, 389 
dwOptions parameter, 470 
DWORDs, 363, 416, 422, 468 
desktop connectivity and, 640 
IrSock and, 581, 586, 589 
processes and, 497, 502 
dwPageSize field, 354 
dwPlatformID field, 808 
dwProcessorRevision field, 354 
dwProvSpeci1 field, 554 
dwProvSpec2 field, 554 
dwProvSubType field, 554 
dwScope parameter, 585 
dwSeekType parameter, 426 
dwServiceMask field, 554 
dwSettableParams field, 554 
dwsSettableStopParity field, 554 
dwSettableData field, 554 
dwShareMode parameter, 382 
dwsize field, 219, 220, 426 
dwSize parameter, 359, 362, 363, 420, 762 
dwStack parameter, 502 
dwStackSize parameter, 502 
dwsStyle parameter, 150, 277, 295 
dwTotalPageFile field, 355 
dwTotalPhys field, 355 
dwTotalVirtual field, 355 
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dwtType field, 587 
dwusage field, 585 
dwValue parameter, 427 


E 
Edit control class, 170, 173 
EditDlg.c, 250-52 
Edit menu, position of, on the command bar, 
280 
EditWnd.c, 193-95 
Ellipse function, 73 
ellipses, drawing, 75-76 
ellipsis C..), 129 
emulators, 16-17, 19 
EnableHardwareKeyboard function, 95 
EnableMenultem routine, 147 
EndDialog function, 214, 218 
END keyword, 129, 210 
EndPaint function, 29, 30, 37 
EnterCriticalSection function, 514, 515 
EntireNet string, 586 
EnumFontFamilies function, 53, 61 
errors. See also debugging; exception 
handling 
clearing, 555-56 
the database API and, 424, 425 
the file API and, 384, 385 
file filters and, 687, 689, 705 
HelloCE and, 17, 18 
IrSock and, 580, 582-84, 586-87, 600, 602, 
604, 610-11, 628 
mutexes and, 513-14 
RAPI connections and, 636—37 
the registry API and, 470, 472 
serial communications and, 555-56 
synchronization and, 508 
EscapeCommFunction function, 555, 558 
ES_LOWERCASE style flag, 173 
ES_MULTILINE style flag, 173 
ES_PASSWORD style flag, 173 
ES_READONLY style flag, 173 
ES_UPPERCASE style flag, 173 
Ethernet cards, 577 
ETK (Embedded Toolkit) 
serial communications and, 540, 544-45, 
548, 550, 552 
shell programming and, 726 
EV_DSR flag, 547 


EVENTPARITY constant, 551 
events, 508-14, 547-48 
EV_ERR flag, 547 
EV_RLSD flag, 547 
EV_RXCHAR flag, 547 
EV_RXFLAG flag, 547, 551 
EV_TXEMPTY flag, 547 
example programs 
AlbumDB program, 435-67 
Calc program, 497, 715-16, 800, 801 
CeChat program, 560-77 
CEFind program, 743-47 
CmdBand program, 304-19 
CmdBar program, 280-94 
CnctNote program, 671-80 
CtlView program, 176-208, 261 
DivFile program, 691-705 
DlgDemo program, 226-61 
FileView program, 389-407 
FontList2 program, 153-69 
FontList program, 53-62 
HelloCE program, 3-21, 32-33 
KeyTrac program, 95-105 
ListNet program, 591-99 
LView program, 326-46 
myapp program, 667-68 
MyNotify program, 731-42 
MySqurt program, 612-26 
RapiDir program, 644-48 
RapiFind program, 653-62 
Shapes program, 77-86 
TBIcons program, 718-25 
TextDemo program, 40—47 
TicTacl program, 114-25 
TicTac2 program, 133-47 
XTalk program, 518-31 
exception handling, 531-30. See also errors 
ExitProcess function, 494, 497 
ExitThread function, 497, 503 
expanded memory, 351. See also memory 
explicit linking, 805-8 
Explorer, 33, 298, 709, 581 
boot process and, 797, 800, 801-2 
Calc applet and, 800, 801 
command line parameters and, 19 
EXE file for, 494, 599 
lack of, for the Palm-size PC, 18 
system configuration and, 802 
extended memory, 351. See also memory 


F 

FAbortOnError field, 550 
fAllocationType parameter, 360 
[Binary field, 550 

FD_CLR macro, 610 

FD_ISSET macro, 610 

FD_SET macro, 611 


-FD_ZERO macro, 611 


Erase field, 30 

fErrorChar field, 550 

fields 
ActionFlags field, 727, 728 
Address field, 629 
AllocationBase field, 363 
Baudkate field, 549, 553 
biBitCount field, 67 
biClrImportant field, 67 
biCompression field, 67 
biPlanes field, 67 
biWidth field, 67 
biXPelsPerMeter field, 67 
biYPelsPerMeter field, 67 
bLastMove field, 147 
ByteSize field, 551 
cbInQue field, 556 
cbOutQue field, 556 
cbSize field, 168, 169, 297, 751 
cbStructure field, 584 
cbWndExtra field, 22, 152 
cDayState field, 321 
clrBack field, 298 
CUID field, 172 
CilType field, 172 
cxIdeal field, 298 
cxMinChild field, 298 
cyMinChild field, 298 
dwAllocationGranularity field, 354 
dwAvailPageFile field, 355, 356 
dwAvailPhys field, 355 
dwAvailVirtual field, 355 
dwCurrentRxQueue field, 554 
dwCurrentTxQueue field, 554 
dwDbaseType field, 423 
dwDevNum field, 583 
dwlength field, 355 
dwMaxBaud field, 553 
dwMaxRxQueue field, 554 
dwMaxTxQueue field, 554 


index 
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fields, continued 
dwMemoryLoad field, 355 
dwOID field, 389 
dwPageSize field, 354 
dwPlatformID field, 808 
dwProcessorRevision field, 354 
dwProvSpeci field, 554 
dwProvSpec2 field, 554 
dwProvSubType field, 554 
dwServiceMask field, 554 
dwSettableParams field, 554 
dwsSettableStopParity field, 554 
dwSetttableData field, 554 
dwsSize field, 219, 220, 426 
dwTotalPageFile field, 355 
dwTotalPhys field, 355 
dwTotalVirtual field, 355 
dwType field, 587 
dwusage field, 585 
FAbortOnError field, 550 
[Binary field, 550 
fErase field, 30 
fErrorchar field, 550 
Flags field, 628 
Mask field, 168, 169, 297, 298, 299 
[Maximized field, 303 
JnBar field, 169, 175 
[Parity field, 550 
Restore field, 30 
fsState field, 272, 273, 297 
hCursor field, 23 
iBitmap field, 272 
iImage field, 298, 300 
irdaAddressFamily field, 603 
irdaServiceName field, 603 
itemAction field, 172 
itemData field, 172 
itemState field, 172 
ifClipPrecision field, 49 
lfEscapement field, 49 
ifFaceName field, 49 
lfHeight field, 49 
lfOrientation field, 49 
lfOutPrecision field, 49 
}fPitchAndFamily field, 49 
ifQuality field, 49 
ifWeight field, 49 
LfWidth field, 49 
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lpCharSet field, 49 
lpComment field, 587 


lpMaximumApplicationAddress field, 354 
lpMinimumApplicationAddress field, 354 


lpszMenuName field, 23 
lpText field, 298 
nPos field, 168, 169 
nTrackPos field, 169 
Options field, 629 
pcRefCount field, 221 
pfnCallBack field, 220, 221 
DfnDigProc field, 221 
Protect field, 363, 365 
rcPaint field, 30 
rcSipRect field, 752, 761, 762 
Reserved field, 93 
RoundTripTime field, 629 
State field, 363, 365 
Status field, 629 
StopBits field, 551 
szDatabaseName field, 423 
szDescription field, 600 
szFullPath field, 689 
szSystemStatus field, 600 ~ 
tmAscent field, 51 
tmDescent field, 51 
itmExternalLeading field, 51, 62 
tmHeight field, 51, 62 
tmInternalLeading field, 51 
Type field, 363, 365 
wPacketLength field, 553 
wPacketVersion field, 553 
file API, 379-417 
file I/O 
basic description of, 381 
accessing device drivers with, 544 
memory-mapped files and, 408 
File menu 
key combinations, 131-32 
position of, on the command bar, 280 
filenames 
extensions for, 65, 682-83, 716 
IrSock and, 580-81 
Windows CE format for, 381 


File Open dialog box, 150, 208, 224, 225, 581 


files. See also file API; file I/O; filenames 
closing, 385 
compression of, 67, 381, 386-87 
communicating with, 518 
creating, 382-84 
downloading, 18-19 
finding, 413-15 
information for, 129, 386-89 
opening, 150, 208, 224, 225, 382-84, 581 
reading, 384-89 
truncating, 386 
writing, 384-89, 408 
File Save dialog box, 150 
FileSys, 493, 795-96, 799, 802 
FILESYS.EXE, 493, 795-96 
FILETIME structure, 387, 388 
FileView program, 389-407 
FileView.c, 392-99, 407 
FileView.h, 390-92 
FileView.rc, 389-90 
FileWrite function, 408 
filters 
basic description of, 680-706 
DivFile program for, 691-705 
interfaces for, 687-91 
FindClose procedure, 413, 414, 415 
Find dialog box, 208, 224 
FindFirstDatabase function, 642 
FindFirstFile procedure, 413-15, 433, 581 
FindNextDatabase function, 642 
FindNextFile procedure, 414, 433, 581 
FindNext procedure, 413 
FindSrv.cpp, 654-58 
FindWindow function, 517, 730 
flags 
BS_2STATE flag, 171 
BS_AUTO2STATE flag, 171 
BS_AUTOSSTATE flag, 206 
BS_AUTOCHECKBOxX flag, 171, 206 
BS_AUTORADIOBUTTON flag, 171, 206 
BS_BOTTOM flag, 171 
BS_CHECKBOxX flag, 171 
BS_ICON flag, 172 
BS_LEFT flag, 171 
BS_MULTILINE flag, 171 
BS_OWNERDRAW flag, 172 
BS_RADIOBUTTON flag, 171 
BS_RIGHT flag, 171 


Index 


flags, continued 


BS_TOP flag, 171 

CCS_VERT flag, 295 
CEDB_ALLOWREALLOC flag, 430 
CEDB_AUTOINCREMENT flag, 424 
CEDB_MAXPROPDATASIZE flag, 418 
CEDB_MAXRECORDSIZE flag, 418 
CEDB_PROPDELETE flag, 432 
CEDB_PROPNOTFOUND flag, 431 
CEDB_SEEK_BEGINNING flag, 427 
CEDB_SEEK_CEOID flag, 427 
CEDB_SEEK_CURRENT flag, 427 
CEDB_SEEK_END flag, 427 
CEDB_SEEK_VALUEFIRSTEQUAL flag, 427 
CEDB_SEEK_VALUEGREATER flag, 427 
CEDB_SEEK_VALUENEXTEQUAL flag, 427 
CEDB_SEEK_VALUESMALLER flag, 427 
CEDB_SORT_CASEINSENSITIVE flag, 422 
CEDB_SORT_DESCENDING flag, 422 
CEDB_SORT_UNKNOWNFIRST flag, 422 


~ CEDB_VALIDCREATE flag, 423 


CEDB_VALIDDBFLAGS flag, 423 
CEDB_VALIDMODTIME flag, 423 
CEDB_VALIDNAME flag, 423 
CEDB_VALIDSORTSPEC flag, 423 
CEDB_VALIDTYPE flag, 423 
CLRBREAK flag, 555 

CLRDTR flag, 555 

CLRIR flag, 555 

CLRRTS flag, 555 

CMDBAR_HELP flag, 279 
CMDBAR_OK flag, 279 
CW_USEDEFAULT flag, 24 
DCX_LOCKWINDOWUPDATE flag, 38 
DCX_NORESETATTRS flag, 38 
DCX_PARENTCLIP flag, 38 
DCX_VALIDATE flag, 38 
DS_ABSALIGN flag, 209 
DS_CENTER flag, 209 
DS_MODALFRAME flag, 209 
DS_SETFONT flag, 210 
DS_SETFOREGROUND flag, 210 
DTR_CONTROL_DISABLE flag, 550 
DTR_CONTROL_ENABLE flag, 550 
DTR_CONTROL_HANDSHAKE flag, 550 
DTS_APPCANPARSE flag, 322 
DTS_IC_DATE_CLASSES flag, 322 
DTS_LONGDATEFORMAT flag, 322 
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flags, continued 
DTS_SHORTDATEFORMAT flag, 322 
DTS_SHOWNONE flag, 322 
DTS_TIMEFORMAT flag, 322 
DTS_UPDOWN flag, 322 
ES_LOWERCASE flag, 173 
ES_MULTILINE flag, 173 
ES_PASSWORD flag, 173 
ES_READONLY flag, 173 
ES_UPPERCASE flag, 173 
EV_DSR flag, 547 
EV_ERR flag, 547 
EV_RLSD flag, 547 
EV_RXCHAR flag, 547 
EV_RXFLAG flag, 547, 551 
EV_TXEMPTY flag, 547 
GENERIC_READ flag, 382, 408 
GENERIC_WRITE flag, 382, 408 
GWL_EXSTYLE flag, 152 
GWL_ID flag, 152 
GWL_STYLE flag, 152 
GWL_USERDATA flag, 152 
GWL_WNDPROC flag, 152 
HEAP_NO_SERIALIZE flag, 368, 369 
HEAP_REALLOC_IN_PLACE_ONLY 
flag, 369 
HEAP_ZERO_MEMORY flag, 368, 369 
ICC_BAR_CLASSES flag, 266 
ICC_COOL_CLASSES flag, 266 
ICC_DATE_CLASSES flag, 266, 319 
ICC_LISTVIEW_CLASSES flag, 266, 324 
ICC_PROGRESS_CLASSES flag, 266 
ICC_TAB_CLASSES flag, 266 
ICC_TREEVIEW_CLASSES flag, 266 
ICC_UPDOWN_LCLASSES flag, 266 
KBDI_KEYBOARD_ENABLED flag, 95 
KBDI_KEYBOARD_PRESENT flag, 95 
KEYEVENTF_KEYUP flag, 94-95 
KEYEVENTF_SILENT flag, 94 
LPTR flag, 366 
LVM_GETTEXTENDEDLISTVIEWSTYLE 
flag, 324 | 
LVM_INSERTITEM flag, 267 
LVM_SETTEXTENDEDLISTVIEWSTYLE 
flag, 324 
LVN_GETDISPINFO flag, 325, 465 
LVN_ODCHACHEHINT flag, 325-26 
LVN_ODFINDITEM flag, 325 
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LVS_AUTOARRANGE flag, 325 
LVS_EX_CHECKBOXES flag, 324, 325 
LVS_EX_FLATSB flag, 325 
LVS_EX_GRIDLINES flag, 325 
LVS_EX_HEADERDRAGDROP flag, 324 
LVS_EX_INFOTIP flag, 325 
LVS_EX_ONECLICKACTIVATE flag, 325 
LVS_EX_REGIONAL flag, 325 
LVS_EX_SUBITEMIMAGES flag, 325 
LVS_EX_TRACKSELECT flag, 325 
LVS_EX_TWOCLICKACTIVATE flag, 325 
LVS_FULLROWSELECT flag, 325 
LVS_OWNERDATA flag, 324, 325 
LVS_SETITEMPOSITION flag, 325 
LVS_SORTASENDING flag, 325 
LVS_SORTDESCENDING flag, 325 
MCS_DAYSTATE flag, 319 
MCS_MULTISELECT flag, 319 
MCS_NOTODAYCIRCLE flag, 319 
MCS_NOTODAY flag, 319 
MCS_WEEKNUMBERS flag, 319 
MONTHCAL_CLASS flag, 319 
OPEN_ALWAYS flag, 383, 419 
OPEN_EXISTING flag, 383, 419 
PAGE_EXECUTE flag, 360 
PAGE_EXECUTE_READ flag, 360 
PAGE_EXECUTE_READWRITE flag, 360 
PAGE_GUARD flag, 361 
PAGE_NOACCESS flag, 361 
PAGE_NOCACHE flag, 361 
PAGE_READONLY flag, 360 
PAGE_READWRITE flag, 360 
PSH_MODELESS flag, 219 
PSH_PROPSHEETPAGE flag, 219 
PSH_PROPTITLE flag, 219 
PSH_USEPSTARTPAGE flag, 219 
PSP_DLGINDIRECT flag, 220 
PSP_PREMATURE flag, 221-22 
PSP_USECALLBACK flag, 220-21 
PSP_USEREFPARENT flag, 221 
PSP_USETITLE flag, 221 
PST_MODEM flag, 554 
PURGE_RXABORT flag, 555 
PURGE_RXCLEAR flag, 554-55 
PURGE_TXABORT flag, 555 
PURGE_TXCLEAR flag, 554 
QS_ALLINPUT flag, 512 


flags, continued 
QS_INPUT flag, 512 
QS_KEY flag, 512 
QS_MOUSEBUTTON flag, 512 
QS_MOUSE flag, 512 
QS_MOUSEMOVE flag, 512 
QS_PAINT flag, 512 
QS_POSTMESSAGE flag, 512 
QS_SENDMESSAGE flag, 512 
QS_TIMER flag, 512 
RBBIM_CHILD flag, 298 
RBBIM_CHILDSIZE flag, 298 
RBBIM_COLORS flag, 298 
RBBIM_IDEALSIZE flag, 298 
RBBIM_ID flag, 298 
RBBIM_LPARAM flag, 298 
RBBS_BREAK flag, 297 
RBBS_CHILDEDGE flag, 297 
RBBS_FIXEDBMP flag, 297 
RBBS_FIXEDSIZE flag, 297 
RBBS_GRIPPERALWAYS flag, 297 
RBBS_HIDDEN flag, 297 
RBBS_NOGRIPPER flag, 297, 300, 318 
RBBS_NOVERT flag, 297-98 
RBBS_RBBIM_STYLE flag, 297 
RBS_AUTOSIZE flag, 295 
RBS_BANDBORDERS flag, 295 
RBS_FIXEDORDER flag, 295 
RBS_SMARTLABEIS flag, 295, 298, 300, 318 
RBS_VARHEIGHT flag, 295, 300 
RBS_VERTICALGRIPPER flag, 295 
RESOURCE_CONNECTED flag, 585 
RESOURCE_GLOBALNET flag, 585, 586 
RESOURCE_REMEMBERED flag, 585 
SETBREAK flag, 555 
SETXOFF flag, 555 
SETXON flag, 555 
SIF_DISABLENOSCROLL flag, 169 
SIF_PAGE flag, 169 
SIF_POS flag, 168 
SIF_RANGE flag, 168 
SIF_TRACKPOS flag, 169 
SIPF_DOCKED flag, 751 
SIPF_LOCKED flag, 751 
SIPF_ON flag, 751 
TBSTATE_AUTOSIZE flag, 273 
TBSTATE_BUTTON flag, 273 
TBSTATE_CHECKED flag, 272 
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flags, continued 
TBSTATE_CHECK flag, 273 
TBSTATE_CHECKGROUP flag, 273 
TBSTATE_DROPDOWN flag, 273 
TBSTATE_ENABLED flag, 272 
TBSTATE_GROUP flag, 273 
TBSTATE_HIDDEN flag, 272 
TBSTATE_INDETERMINATE flag, 272 
‘TBSTATE_PRESSED flag, 272 
TBSTATE_SEP flag, 273 
TBSTATE_WRAP flag, 272 
TRUNCATE_EXISTING flag, 383, 419 
WS_CAPTION flag, 209, 210 
WS_CHILD flag, 150, 165, 278 
WS_EX_CAPTIONOKBTN flag, 210 
WS_EX_CONTEXTHELP flag, 210 
WS_GROUP flag, 211 
WS_HSCROLL flag, 167 
WS_OVERLAPPED flag, 150 
WS_POPUP flag, 210 
WS_SYSMENU flag, 209, 210 
WS_TABSTOP flag, 211 
WS_VISIBLE flag, 24, 150, 165, 205, 

278, 374 

WS_VSCROLL flag, 165, 167 

Flags field, 628 

flags parameter, 38, 604 

{Mask field, 168, 169, 297, 298, 299 

[Maximized field, 303 

JnBar field, 169, 175 

{NewProtect parameter, 363 

JnPenStyle parameter, 72 

folders. See also directories 
basic description of, 711 
in ListNet windows, 591 
special, 711-15 

FontFamilyCallback function, 61 

FontList2 program, 153-69 
FontList2.c, 154-59 
FontList2.h, 154-55 
with the scrollbar positioned beneath the 

command bar, 153 

FontList program, 53-62 
FontList.c, 54-61 
FontList.h, 53-54, 61 
window, 62-63 
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fonts, 47-53, 61-62. See also FontList2 
program; FontList program 
characteristics of, querying, 50-51 
enumerating, 52-53 
families of, 49, 52, 61 
files for, including, as resources, 129 
logical, 49, 50, 69 
TrueType fonts, 47-50, 743 
fopen function, 382 
fOptions parameter, 368 
Format menu, position of, on the command 
bar, 280 
FormatMessage function, 689-91 
forward slash (), 128 
Parity field, 550 
Protect parameter, 360, 408 
fread function, 382 
[Redraw parameter, 168 
free memory pages, 352, 356-57 
Free method, 713-14 
FreeLibrary function, 805, 806 
fRestore field, 30 
[Show parameter, 279 
fsModifiers parameter, 791 
fsState field, 272, 273, 297 
functions 
accept function, 601, 603-4 
BeginPaint function, 29-30, 37, 38, 61 
bind function, 601, 604 
BitBit function, 69, 70 
CeCheckPassword function, 638 
CeCloseHandle function, 638 
CeCopyFile function, 639 
CeCreateDatabaseEx function, 421, 423, 
429, 435, 641 
CeCreateDatabase function, 418, 421, 423, 
634, 641 
CeCreateDirectory function, 639 
CeCreateFile function, 638 
CeCreateProcess function, 638 
CeDatabaseEx function, 433 
CeDatabaseSeek function, 429 
CeDeleteDatabaseEx function, 641 
CeDeleteDatabase function, 641 
CeDeleteFile function, 639 
CeDeleteRecord function, 641 
CeEnumDBVolumes function, 420 
CeFindAllDatabases function, 642, 643 
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CeFindAllFiles function, 638, 642, 643, 648 
CeFindClose function, 638 
CeFindFirstDatabaseEx function, 641 
CeFindFirstDatabase function, 433, 641 
CeFindFirstFile function, 638 
CeFindNextDatabaseEx function, 641 
CeFindNextDatabase function, 433, 641 
CeFindNextFile function, 638 
CeGetDesktopDeviceCaps function, 638 
CeGetFileAttributes function, 638 
CeGetFileSize function, 639 
CeGetFileTime function, 639 
CeGetStoreInformation function, 634, 
637, 638 
CeGetSystemInfo function, 638 
CeGetSystemMetrics function, 638 
CeGetSystemPowerStatusEx function, 638 
CeGetVersionEx function, 635, 638 
CeGlobalMemoryStatus function, 638 
CeMoundDBVol function, 419-20, 642 
GeMoveFile function, 639 
CeOidGetInfoEx function, 641 
CeOidGetInfo function, 641 
CeOpenDatabaseEx function, 425, 641 
CeOpenDatabase function, 425, 641 
CeRapiFreeBuffer function, 643 
CeRapiGetError function, 637 
CeRapilnitEx function, 636, 647 
CeRapilnit function, 636, 648, 662 
CeRapilnvoke function, 648-49, 651-53, 662 
CeRapiUninit function, 636 
CeReadFile function, 638 
CeReadRecordPropsEx function, 430, 431, 
432, 641 
CeReadRecordProps function, 430, 431, 641, 
643, 465 
CeRemoveDirectory function, 639 
CeRunAppAtEvent function, 680 
CeSeekDatabase function, 428, 641 
CeSetDatabaseInfo function, 422, 435 
CeSetDatabaseInfoEx function, 641 
CeSetEndOfFile function, 638 
CeSetFilePointer function, 638 
CeSetFileTime function, 639 
CeSetUserNotification function, 726-28 
CeSvcOpen function, 664, 665, 667-68, 684 
CeUnmountDBVol function, 420, 642 
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CeUtil functions, 662-67, 681, 684 

CeWriteFile function, 638 

CeWriteRecordProps function, 432, 641 

ClearCommBreak function, 554-55 

ClearCommeError function, 556 

CloseFile function, 382 

CommandBar_AddAdornments function, 
28, 279 

CommandBar_AddBitmap function, 270, 
271-72, 274 

CommandBar_Create function, 28 

CommandBar_Destroy function, 30-31 

CommandBar_DrawMenubar function, 269 

CommandBar_Height function, 29, 279 

CommandBar_InsertComboBox 
function, 278 

CommandBar_InsertMenubar 
function, 269 

ComposeLine function, 407 

connect function, 601, 612 

CopyFile function, 412 

CreateBitmap function, 67 

CreateDialog function, 218 

CreateDIBPatternBrushPt function, 74, 85 

CreateDIBSection function, 67, 68 

CreateDirectory function, 412 

_ CreateEvent function, 508, 509 

CreateFileForMapping function, 408 

CreateFile function, 382-84, 387, 407-8, 
419, 544, 546 

CreateFileMapping function, 409, 
410-12, 529 

CreateFontIndirect function, 49 

CreateHatchBrush function, 85 

CreateMenu function, 126 

CreateMessage function, 217 

CreatePenIndirect function, 72-73 

CreateProcess function, 494-97, 502 

CreateThread function, 502, 503 

CreateWindowEx function, 170, 324 

CreateWindow function, 24, 25, 27, 150, 
165, 170, 206, 324 

DefWindowProc function, 26, 32, 208, 213 

DeleteDC function, 70 

DeleteFile function, 412, 413 

DeleteObject function, 62 

DestroyCommandBand function, 318 
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DispatchMessage function, 21, 132, 213, 217 
DilMain function, 767 
DoCreateBinWind function, 206 
DoCreateMain function, 27—28, 465 
DoDestroyMain function, 32 
DoMainCommandColor function, 261 
DoMainCommanaPrint function, 261 
DoPaintClient function, 166 
DrawMenuBar function, 269 
DrawText function, 30, 33, 35, 39, 46, 
51, 61-62 
DuplicateHandle function, 516 
Ellipse function, 73 
EnableHardwareKeyboard function, 95 
EndDialog function, 214, 218 
EndPaint function, 29, 30, 37 
EnterCriticalSection function, 514, 515 
EnumFontFamilies function, 53, 61 
EscapeCommFunction function, 555, 558 
ExitProcess function, 494, 497 
ExitThread function, 497, 503 . 
FileWrite function, 408 
FindFirstDatabase function, 642 
FindNextDatabase function, 642 
FindWindow function, 517, 730 
FontFamilyCallback function, 61 
fopen function, 382 
FormatMessage function, 689-91 
fread function, 382 
FreeLibrary function, 805, 806 
GetCapture function, 113, 114 
getc function, 742 
GetClientRect function, 29 
GetCommandLine function, 494 
GetCommProperties function, 550, 553 
GetCommsState function, 548—49, 560 
GetDC function, 38, 70 
GetDeviceCaps function, 40, 49, 73, 809 
GetDialogBaseUnits function, 209 
GetDiskFreeSpaceEx function, 416, 648, 651 
GetDigitem function, 31, 32, 278 
GetExceptionCode function, 534 
GetExceptionInformation function, 534 
GetFileInformationByHandle function, 388 
GetFileSize function, 388, 407 
GetFileTime function, 387 
GetKeyboardStatus function, 95 
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GetKeyState function, 93-94, 106, 114 
GetLastError function, 384-85, 424~25, 
508, 513-14, 517, 529, 582, 586-87, 628, 
636-37 
GetMessage function, 20, 21, 213, 502 
GetMouseMovePoints function, 106-7 
GetObject function, 70 
GetProcAddress function, 95, 261, 369, 635, 
805, 806 
GetScrollInfo function, 169, 175 
GetStockObject function, 72, 73, 84 
GetStoreInformation function, 355, 416, 
634, 637 
GetSysColorBrush function, 207 
GetSystemInfo function, 354 
GetTextColor function, 40 
GetVersionEx function, 95, 802-3, 808 
GetVersion function, 802—3 
GetWindowDC function, 70 
GetWindow function, 151 
GetWindowLong function, 152 
GetWindowPos function, 27 
GlobalAlloc function, 359 
GlobalFree function, 359 
GlobalMemoryStatus function, 354, 355 
GlobalRealloc function, 359 
HeapCreate function, 367 
HeapDestroy function, 369 
HeapReAlloc function, 369 
IcmpCloseHandle function, 629 
IcmpCreateFile function, 627, 629 
IcmpSendEcho function, 627, 628, 629, 631 
ImageList_Create function, 296 
ImageList_Duplicate function, 275 
inet_addr function, 629 
InitCommoncControlsEx function, 319, 
321-22 
InitCommoncontrols function, 319, 324 
InvalidateRect function, 104 
IOCTLI_CLR_DTR function, 544—45 
IOCTI_CLR_RTS function, 544-45 
IOCTL_DISABLE_IR function, 544—45 
IOCTL_GET_COMMSTATUS function, 
544—45 
IOCTL_GET_DCB function, 544—45 
IOCTL_GET_MODEMSTATUS function, 
544-45 
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IOCTL_GET_PROPERTIES function, 544—45 
IOCTL_GET_TIMEOUTS function, 544-45 
IOCTL_GET_WAIT_MASK function, 544-45 
IOCTL_IMMEDIATE_CHAR function, 544—45 
JOCTL_PURGE function, 544-45 
IOCTL_SERIAL_ENABLE_IR function, 
544-45 
IOCTI_SET_BREAK_OFF function, 544—45 
IOCTL_SET_BREAK_ON function, 544—45 
IOCTL_SET_DCS function, 544-45 
IOCTL_SET_DTR function, 544—45 
IOCTL_SET_QUEUE_SIZE function, 544—45 
IOCTL_SET_RTS function, 544—45 
IOCTL_SET_TIMEOUTS function, 544—45 
IOCTL_SET_WAIT_MASK function, 544—45 


JOCTL_SET_XOFF function, 544-45 


IOCTL_SET_XON function, 544—45 
IOCTL_WAIT_ON_MASK function, 544—45 
IsDialogMessage function, 217 
IsSIPInputMethod function, 753 
KernelRelocate function, 795 
KernelStart function, 794-95 
LeaveCriticalSection function, 514, 515 
LibMain function, 649 

listen function, 601, 603 
LoadAccelerators function, 132 
LoadIcon function, 717 

LoadImage function, 65, 130, 132, 717 
LoadLibrary function, 95, 261, 635, 805, 806 
LoadString function, 373 

LocalAlloc function, 365, 366, 651 
LocalFree function, 365 

LocalRealloc function, 365, 367, 369 
lpEnumFunc function, 151 
MapViewOfFile function, 409, 529 
MapVirtualKey function, 95 

MaskBit function, 70 

memcopy function, 69 

MoveFile function, 412-13 
MyCreateHatchBrush function, 85 
NextConvertFile function, 687-89, 704—5 
OnPaintMain function, 46, 61, 84-85 
OpenCreateDB function, 435 
OpenDestinationFile function, 704 
OptionsData function, 628 
OptionsSize function, 628 
PingAddress function, 629 


functions, continued 
PostQuitMessage function, 21, 32, 147 
printf function, 742 
PropertySheet function, 218, 219 
rc VisibleDesktop function, 752 
ReadDonekvent function, 529 
ReadDone function, 530 
ReaderThread function, 528, 530, 531 
ReadEvent function, 529, 530, 531 
ReadFile function, 382, 384-85, 407, 544, 

546-47, 551, 552 
ReadIntervalTimeout function, 551, 552 
ReadTotalTimeoutConstant function, 551 
ReadTotalTimeoutMultiplier function, 551 
rectangle function, 73, 74, 75 
recv function, 601 
RegCreateKeyEx function, 470 
RegEnumKeyEx function, 472-73 
RegisterClass function, 22, 23, 152 
ReleaseCapture function, 113 
ReleaseDC function, 38, 70 
ReleaseMutex function, 514, 529 
RemoveDirectory function, 412 
ResetEvent function, 509 
ResumeCount function, 504 
ResumeThread function, 502, 504 
RoundRect function, 73, 76 
select function, 610, 611 
SelectObject function, 51, 62, 69 
SendCharEvents function, 764, 765-66 
SenderThread function, 528, 530, 531 
send function, 601, 605 
SendMessage function, 130, 267 
SendString function, 764, 766 
SendVirtualKey function, 763, 765 
SetCommBreak function, 554, 555 
SetCommsState function, 548-49, 551 
SetFilePointer function, 385, 407 
SetImInfo function, 763-65 
SetScrollinfo function, 168, 169, 175 
SetupComm function, 552 
SetWindowLong function, 152, 224 
ShowWindow function, 20, 25 
SHSipInfo function, 750-53, 755, 756, 
762, 805 

SignalStarted function, 797 
SipRegisterNotification function, 757 
sleep function, 107, 504—5 
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SrchDirectory function, 658-59, 744 

SuspendtThread function, 504 

TabbedTextOut function, 62 

TerminateProcess function, 498 

TermInstance function, 21, 32 

TisAlloc function, 506-7 

TranslateMessage function, 20-21, 132, 217 

TransmitCommcChar function, 547, 556 

ValidateRect function, 37 

VirtualAlloc function, 359, 361-62, 364 

VirtualFree function, 359, 362 

VirtualProject function, 363 

VirtualQuery function, 363, 364, 365 

VirtualReSize function, 359 

WaitCommEvent function, 547, 548, 551 

WaitForMultipleObjects function, 509, 511, 
512, 531 

WaitForSingleObjects function, 509-11, 529 

WriteFile function, 382, 384, 544, 546-47, 
551-52, 556, 577 

WSAGetLastError function, 600, 602, 604, 
610 

WSAStartup function, 599-600 


GDI (Graphics Device Interface). See also 
GWE (Graphics Windowing and Event) 
handler 

basic description of, 36 

fonts and, 50, 51 

lines and, 72 

memory management and, 358 
objects, selecting, 50 

GENERIC_READ flag, 382, 408 

GENERIC_WRITE flag, 382, 408 

GetCapture function, 113, 114 

getc function, 742 

GetClientRect function, 29 

GetCommandLine function, 494 

GetCommProperties function, 550, 553 

GetCommsState function, 548-49, 560 

GetDC function, 38, 70 

GetDeviceCaps function, 40, 49, 73, 809 

GetDialogBaseUnits function, 209 

GetDiskFreeSpaceEx function, 416, 648, 651 

GetDigitem function, 31, 32, 278 

GetExceptionCode function, 534 
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GetExceptionInformation function, 534 

GetFileInformationByHandle function, 388 

GetFile routine, 626 

GetFileSize function, 388, 407 

GetFileTime function, 387 

GetImData method, 760, 762-63 

GetInfo method, 760-61, 764, 786 

GetKeyboardStatus function, 95 

GetKeyState function, 93-94, 106, 114 

GetLastError function, 384-85, 424-25, 
508, 513-14, 517, 529, 582, 586-87, 628, 
636-37 

GetMessage function, 20, 21, 213, 502 

GetMouseMovePoints function, 106-7 

GetObject function, 70 

GetProcAddress function, 95, 261, 369, 635, 
805, 806 

GetScrollinfo function, 169, 175 

GetStockObject function, 72, 73, 84 

GetStoreInformation function, 355, 416, 
634, 637 

GetSysColorBrush function, 207 

GetSystemInfo function, 354 

GetTextColor function, 40 | 

GetVersionEx function, 95, 802-3, 808 

GetVersion function, 802-3 

GetWindowDC function, 70 

GetWindow function, 151 

GetWindowLong function, 152 

GetWindowPos function, 27 

GlobalAlloc function, 359 

GlobalFree function, 359 

global heap, 359. See also heaps 

GlobalMemoryStatus function, 354, 355 

GlobalRealloc function, 359 

Greenwich Mean Time, 387-88 

Gregorian calendar, 319 

group boxes, 171 

GUI (graphical user interface), 35, 493 

GUIDGEN.EXE, 693 

GWE (Graphics Windowing and Event) 
handler, 36, 787, 794, 799-800 

GWES.EXE, 493, 540, 797, 799-800, SO2 

GWL_EXSTYLE style flag, 152 

GWL_ID style flag, 152 

GWL_STYLE style flag, 152 

GWL_USERDATA style flag, 152 

GWL_WNDPROC style flag, 152 
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H 
HAL (hardware abstraction layer), 794 
half duplex transmissions, 539 
handle data type, 15 
handwriting recognition, 106 
hard disks, absence of, 4 
hardware 
abstraction layer (HAL), 794 
keys, 787-92 
hCursor field, 23 
HeapCreate function, 367 
HeapDestroy function, 369 
HEAP_NO_SERIALIZE flag, 368, 369 
HeapReAlloc function, 369 
HEAP_REALLOC_IN_PLACE_ONLY flag, 369 
heaps 
API for, 358-59, 367-69 
basic description of, 365 
creating, 368 
destroying, 369 
local, 357, 358, 365-67, 431 
HEAP_ZERO_MEMORY flag, 368, 369 
HelloCE program, 3—21, 32-33 
HelloCE.c, 9-14 
HelloCE.EXE, 33 
HelloCE.h, 8-9, 14, 32 
Help About menu, 226 
Help button, 210, 268, 279 
hIcon/pszIcon union, 220-21 
Hiding method, 760, 762 
HKEY_CLASSES_ROOT registry key, 468, 
681, 682 
HKEY_CURRENT_USER registry key, 468, 
663, 681 
HKEY_LOCAL_MACHINE registry key, 468, 
469, 495, 540-42, 558, 581, 663, 681, 
682, 686, 789, 796, 798, 800 
hot spots, for scroll bars, 166 
H/PC (Handheld PC) 
batteries, 350 
Calculator applet, 497 
command bar controls, 298 
cross-platform applications and, 803-4 
CtlView program and, 176 
the database API and, 418 
desktop connectivity and, 633, 635, 705 
File Open dialog box, 225 
fonts available for, 62 


H/PC (Handheld PC), continued 
gray-scale displays used by, 207 
hardware keys and, 787, 791 
input panels and, 753 
IrSock and, 581 
landscape-mode screen, 809 
memory management and, 350, 355—56, 
373-74, 375-76, 377 

new controls for, 5 

PCs and, establishing connections 
between, 17 

Pro, 418, 749, 803 

processes and, 494, 497 

running HelloCE on, 17-18, 32, 33 

serial communications and, 557, 577 

shell programming and, 709-12, 715-16, 
728, 749, 753, 791-92 

Start menu, 715—16 

taskbar, 150 

threads and, 499 

WM_HIBERNATE messages and, 150 

bPrevinstance parameter, 19 

hSection parameter, 68 

bSrc parameter, 70 

hTemplate parameter, 384 

Hungarian notation, 14-15 


I 
iBitmap field, 272 
IBM CUnternational Business Machines), 4, 793 
iButton parameter, 127, 269, 273, 277 
ICC_BAR_CLASSES flag, 266 
ICC_COOL_CLASSES flag, 266 
ICC_DATE_CLASSES flag, 266, 319 
ICC_LISTVIEW_CLASSES flag, 266, 324 
ICC_PROGRESS_CLASSES flag, 266 
ICC_TAB_CLASSES flag, 266 
ICC_TREEVIEW_CLASSES flag, 266 
ICC_UPDOWN_LCLASSES flag, 266 
IceFileFilter interface, 687-91, 694 
IceFileFilterOptions interface, 687, 691 
IceFileFilterSite interface, 688 
IClassFactory interface, 694, 767 
ICmdLine parameter, 19, 20 
ICMP (Internet Control Message Protocol) 
functions, 579, 627 
IcmpCloseHandle function, 629 
IcmpCreateFile function, 627, 629 
IcmpSendEcho function, 627, 628, 629, 631 


index 


ICMPAPLH, 627 
ICMP_ECHO_REPLY structure, 628-31 
icons, 22, 129, 130, 716-18 
IDCANCEL button, 214-16, 223 
IDccMan interface, 667, 669-70, 679 
IDccManSink interface, 669, 670-71, 679 
ID lists, 711, 713-14 
idMenu parameter, 269 
idNewlitem parameter, 125 
IDOK button, 214-16, 223 
IDs 
item IDs, 711 
object IDs, 389, 434-35 
property IDs, 422, 428 
IFS (installable file system), 380 
iImage field, 298, 300 
IIMCallback interface, 759, 762-66, 786 
IInputMethod interface, 758-64, 767, 786 
ImageList_Create function, 296 
ImageList_Duplicate function, 275 
images. See also bitmaps 
lists of, 275, 296 
memory pages for, 356-57 
referencing, 271-73 
IMalloc interface, 713-14 
iMaxSockets parameter, 600 
IME API, 756 
IMENUMINFO structure, 756 
IMINFO structure, 760-61 
indices, in Windows CE databases, 418 
inet_addr function, 629 
infrared transmissions, 539, 557-60. See also 
IrDA (Infrared Data Association); serial 
communications 
InitApp procedure, 14, 20, 21-23, 261 
InitCommoncontrolsEx function, 319, 321-22 
InitCommoncControls function, 319, 324 
InitInstance procedure, 20, 23-25, 528 
inking, 106-7 
input methods 
changing, 753 
enumerating, 753-55 
NumPanel input method, 766-86 
writing, 758-87 
input panels, 753-58. See also SIP (Supple- 
mentary Input Panel) 
Insert menu, position of, on the command 
bar, 280 
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integer data type, 15, 417 
interfaces 
IceFileFilter interface, 687-91, 694 
IceFileFilterOptions interface, 687, 691 
IceFileFilterSite interface, 688 
IClassFactory interface, 694, 767 
IDccMan interface, 667, 669-70, 679 
IDccManSink interface, 669, 670-71, 679 
IIMCallback interface, 759, 762-66, 786 
IInputMethod interface, 758-64, 767, 786 
IMalloc interface, 713-14 
IRAPIStream interface, 652-54, 658-59 
IStream interface, 688 
IUnknown interface, 763, 759 
interlocked variable access, 515-16 | 
interprocess communication, 516-31. See also 
DLLs (dynamic-link libraries) 
InvalidateRect function, 104 
I/O Ginput/output). See also IOCTL (device 
I/O control) functions 
file, 381, 408, 544 
library functions, 742-43 
overlapped I/O, 547 
IOCTL (device I/O control) functions, 
544-45, 548 
IOCTLI_CLR_DTR function, 544-45 
IOCTL_CLR_RTS function, 544—45 
JOCTL_DISABLE_IR function, 544-45 
IOCTL_GET_COMMSTATUS function, 
544-45 
IOCTL_GET_DCB function, 544—45 
IOCTL_GET_MODEMSTATUS function, 
544—45 
IOCTL_GET_PROPERTIES function, 544—45 
IOCTI_GET_TIMEOUTS function, 544-45 
IOCTL_GET_WAIT_MASK function, 544—45 
IOCTL_IMMEDIATE_CHAR function, 544-45 
IOCTL_PURGE function, 544-45 
IOCTL_SERIAL_ENABLE_IR function, 
544-45 
IOCTL_SET_BREAK_OFF function, 544—45 
IOCTL_SET_BREAK_ON function, 544-45 
IOCTLI_SET_DCS function, 544—45 
IOCTL_SET_DTR function, 544-45 
IOCTL_SET_QUEUE_SIZE function, 544-45 
IOCTLI_SET_RTS function, 544-45 
IOCTL_SET_TIMEMOUTS function, 544—45 
IOCTLI_SET_WAIT_MASK function, 544—45 
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IOCTL (device I/O control) functions, 
continued 
IOCTL_SET_XOFF function, 544—45 
IOCTLI_SET_XON function, 544—45 
JOCTL_WAIT_ON_MASK function, 544-45 
IRAPIStream interface, 652-54, 658-59 
IrComm mode, 557, 559-60 
IrDA (Infrared Data Association), 555, 557-60, 
579. See also serial communications 
address resolution features, 603 
sockets, 602 
stack, 606 
irdaAddressFamily field, 603 
IRDA_DEVICE_INFO structure, 606 
irdaServiceName field, 603 
IrSock, 557, 560 
basic description of, 579-631 
ListNet program and, 591-99 
MySqurt program and, 612-26 
options, 608-9 
ISA (Industry Standard Architecture) bus, 540 
IsDialogMessage function, 217 
IsSIPInputMethod function, 753 
IStream interface, 688 
Italic button, position of, on the command 
bar, 280 
italic font, 49 
itemAction field, 172 
itemData field, 172 
item IDs, 711 
itemState field, 172 
IUnknown interface, 763, 759 
iUsage parameter, 68 
iWidth parameter, 277 


K 
KBDI_KEYBOARD_ENABLED flag, 95 
KBDI_KEYBOARD_PRESENT flag, 95 
Kbps (kilobits per second), 549-50 
kernel, 36, 358, 794-802 
KernelRelocate function, 795 
KernelStart function, 794-95 
keyboard. See also KeyTrac program 

accelerator tables, defining, 129, 131-32 

device drivers, 540 

flags, 94-95 

functions, 93-95 

input, basic description of, 87-105 


keyboard, continued 

messages, 88-93 

soft, 87 

testing for, 95 

virtual key codes for, 89-91, 788-89 
KEYEVENTF_KEYUP flag, 94-95 
KEYEVENTF_SILENT flag, 94 
KeyTrac program, 95-105 

KeyTrac.c, 98-104 

KeyTrah.h, 96-97 

window after a Shift-A key combination 

and a lowercase key press, 96 

keywords 

BEGIN keyword, 129, 210 

catch keyword, 531 

const keyword, 372 

CONTROL keyword, 131, 210-11 

DIALOG keyword, 209 

discardable keyword, 129, 209 

END keyword, 129, 210 

MENUITEM keyword, 129 

throw keyword, 531 


L 


LeaveCriticalSection function, 514, 515 
LEDs Cight-emitting diodes), 726, 727, 
728, 729 
IfClipPrecision field, 49 
lfEscapement field, 49 
lfFaceName field, 49 
lfHeight field, 49 
lfOrientation field, 49 
lfOutPrecision field, 49 
]fPitchAndFamily field, 49 
IfQuality field, 49 
lfWeight field, 49 
IfWidth field, 49 
LibMain function, 649 
light-emitting diodes (LEDs), 726, 727, 
728, 729 
lines 
drawing, 71-73 
height of, 51, 62 
width of, 71-72 
linking, explicit, 805-8 
List control class, 170, 173—74 
ListDlg.c, 252-55 
listen function, 601, 603 


index 


listen mode, 603—4 
ListNet program, 591-99 
ListNet.c, 593-99 
ListNet.h, 592-93 
ListNet.rc, 592 
window, 591 
list view control 
basic description of, 324-26 
LView program and, 326-46 
virtual, 325-26 
ListWnd.c, 195-98 
LoadAccelerators function, 132 
LoadIcon function, 717 
LoadImage function, 65, 130, 132, 717 
LoadLibrary function, 95, 261, 635, 805, 806 
LoadString function, 373 
LocalAlloc function, 365, 366, 651 
LocalFree function, 365 
local heap, 357, 358, 305-67, 431. See also 
heaps 
LocalRealloc function, 365, 367, 369 
LOGFONT structure, 48, 49, 51, 53 
LOGPEN structure, 72 
long data type, 15 
LONG macro, 422 
loops, 16, 20-21, 26, 131-32, 217 
low-memory conditions, 4, 350, 370, 374-77, 
725, 726 
low-power modes, 501-2 
lpAddress parameter, 362, 363, 364 
lpApplicationName parameter, 495 
lParam parameter, 26, 52, 61, 92, 93, 95, 106, 
114, 123, 125, 127, 151, 166, 172-73, 212, 
216, 221-23, 298, 274, 276, 717, 758, 792 
IpBuffer parameter, 132, 273, 385, 586, 
587, 590 
IpBytesReturned parameter, 544 
IpCharSet field, 49 
lpCmdline parameter, 497 
lpCommandLine parameter, 495 
lpComment field, 587 
IpcPropID parameter, 430 
IpData parameter, 470 
lpEnumFunc function, 151 
IpEventAttributes parameter, 508 
lpHandles parameter, 511 
IpLibFileName parameter, 805 
lpMaximumApplicationAddress field, 354 
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IpMinimumApplicationAddress field, 354 
lpName parameter, 409, 508, 513 
IpNetResource parameter, 582, 585 
IpNewltem parameter, 126 
IpnLength parameter, 589, 591 
IpOutBuffer parameter, 544 
IpOverlapped parameter, 384, 385, 548 
IpParameter parameter, 502 
IpProcessInformation parameter, 496 
IpRect parameter, 37 
IpSecurityAttributes parameter, 382, 470 
IpszClassName parameter, 23 
IpszMenuName field, 23 
lpszName parameter, 424 
IpszNewltem parameter, 125 
lpszValueName parameter, 470 
lpText field, 298 
lpTbhreadAttributes parameter, 502 
IpTime parameter, 727, 730 
lpToolTips parameter, 278 
LPTR flag, 366 
lpType parameter, 470 
[pUserName parameter, 591 
LRESULT return type, 26 
LSAP (Logical Service Assess Point) 
selectors, 603 
LView program, 326-46 
Lview.c, 330—46 
Lview.h, 32830 
Lview.rc, 327-28 
window, 326 
LVM_GETTEXTENDEDLISTVIEWSTYLE style 
flag, 324 
LVM_INSERTITEM style flag, 267 
LVM_SETTEXTENDEDLISTVIEWSTYLE style 
flag, 324 
LVN_GETDISPINFO style flag, 325, 465 
LVN_ODCACHEHINT style flag, 325-26 
LVN_ODFINDITEM style flag, 325 
LVS_AUTOARRANGE style flag, 325 
LVS_EX_CHECKBOXES style flag, 324, 325 
LVS_EX_FLATSB style flag, 325 
LVS_EX_GRIDLINES style flag, 325 
LVS_EX_HEADERDRAGDROP style flag, 324 
LVS_EX_INFOTIP style flag, 325 
LVS_EX_ONECLICKACTIVATE style flag, 325 
LVS_EX_REGIONAL style flag, 325 
LVS_EX_SUBITEMIMAGES style flag, 325 
LVS_EX_TRACKSELECT style flag, 325 
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LVS_EX_TWOCLICKACTIVATE style flag, 325 
LVS_FULLROWSELECT style flag, 325 
LVS_OWNERDATA style flag, 324, 325 
LVS_SETITEMPOSITION style flag, 325 
LVS_SORTASCENDING style flag, 325 
LVS_SORTDESCENDING style flag, 325 


M 
macros 
defined in WINSOCK.H, 610-11 
FD_CLR macro, 610 
FD_ISSET macro, 610 
FD_SET macro, 611 
FD_ZERO macro, 611 
LONG macro, 422 
MAKEINTRESOURCE macro, 130, 212 
MAKELONG macro, 422 
MAKEWORD macro, 599 
RGB macro, 72-73 
TEXT macro, 24, 39, 639 
MainMessages table, 26 
MainWndProc procedure, 25—27 
MAKEINTRESOURCE macro, 130, 212 
MAKELONG macro, 422 
MAKEWORD macro, 599 
MapViewOfFile function, 409, 529 
MapVirtualKey function, 95 
MaskBit function, 70 
masking images, 70 
MCS_DAYSTATE flag, 319 
MCS_MULTISELECT flag, 319 
MCS_NOTODAYCIRCLE flag, 319 
MCS_NOTODAY flag, 319 
MCS_WEEKNUMBERS flag, 319 
memcopy function, 69 
memory. See also memory maps 
64-KB limit, 354, 361-62, 370 
address space, 352-58 
allocating, 358-77 
basic description of, 349-77 
bitmaps and, 66, 68 
boot process and, 794-95 
device contexts:and, 68—70 
freeing, 362, 366, 368 
loading strings into, 132 
low-memory conditions, 4, 350, 370, 
374-77, 725, 726 
message tables and, 27 
minimizing the use of, 27, 30-31, 132 


memory, continued 
Out Of Memory dialog box, 725, 726 © 
regions vs. pages, 361-62 
resizing, 366-67, 369 
serial communications and, 545 
stack, 370, 373, 376-77 
static data area, 370-73, 374 
system, querying, 354—56 
thresholds, 375-76, 377 
types, selecting the proper, 373-74 
memory maps, 408-12, 517-18, 545. See also 
memory 
application address space and, 356-58 
diagrams of, 353, 356-57, 371-72 
showing the size of data segments, 371-72 
the Windows CE address space and, 352-56 
MEMORYSTATUS structure, 355 
MENUITEM keyword, 129 
MENU resource type, 129 
menus 
commands on, handling, 127 
creating, 125-26 
defining, as resources, 129 
input for, handling, 87, 125-26 
items on, checking/unchecking, 126 
items on, querying, 126 
templates for, 128-29 
messages. See also notifications 
BN_CLICKED message, 170, 171, 206 
DB_CEOID_CHANGED message, 424-25 
DB_CEOID_CREATED message, 424—26 
DB_CEOID_RECORD_DELETED message, 
424—25 
DTN_FORMAT message, 324 
DTN_FORMATQUERY message, 324 
DTN_USERSTRING message, 322 
DTN_WMKEYDOWN message, 324 
PSM_ADDPAGE message, 221 
PSM_REMOVEPAGE message, 221 
PSN_KILLACTIVE message, 223 
WM_ACTIVATE message, 31 
WM_CAPTURECHANGED message, 114 
WM_CHAR message, 89, 92, 97, 750, 764, 
765, 788 
WM_CLOSE message, 147, 497, 498, 792 
WM_COMMAND message, 127, 129, 131, 
147, 170, 176-75, 205-7, 214, 216, 223, 
226, 260-61, 267, 273, 275, 277-79, 530 
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messages, continued 


WM_COPYDATA message, 517-18 
WM_CREATE message, 7, 25, 27, 31, 61, 
125, 165, 205, 213 
WM_DBNOTIFICATION message, 425, 426 
WM_DEADCHAR message, 93 
WM_DESTROY message, 32, 147 
WM_DRAWITEM message, 172, 206-7 
WM_HIBERNATE message, 30-31, 150, 
374-77 
WM_HSCROLL message, 169, 175, 207 
WM_INITDIALOG message, 213, 216, 
222, 261 
WM_KEYDOWN message, 88-89, 92, 97, 
750, 764, 788 
WM_KEYUP message, 89, 92, 97, 750, 
764, 788 
WM_LBUTTONDOWN message, 105-6, 
107, 717 
WM_LBUTTONUP message, 106, 123, 717 
WM_MOUSEMOVE message, 106, 107, 113 
WM_MOVE message, 7, 8 
WM_NOTIFY message, 223, 224, 226, 260, 
267, 275, 303, 320, 405, 491 
WM_PAINT message, 25, 28, 29, 30, 36, 37, 
38, 61, 104, 166, 214, 407 
WM_RBUTTONDOWN message, 114 
WM_RBUTTONUP message, 114 
WM_SETFOCUS message, 88 
WM_SETTINGCHANGE message, 322 
WM_SIZE message, 123, 679 
WM_SYSCHAR message, 89, 92 
WM_SYSKEYDOWN message, 89 
WM_SYSKEYUP message, 89 
WM_VSCROLL message, 166, 169, 175, 207 


microprocessors, 794, 801 


exception handling and, 534 

memory management and, 351-52, 354, 
356, 305, 373-74 

that support Windows CE, 3 

system programming and, 793-94, 801 

target, selecting, 16 

threads and, 499, 501 


Microsoft Pocket Word 


configuration information, in the registry, 
468, 469, 470 

converter, 681 

file format (PWD format), 681, 683 

Find dialog box in, 208 
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Microsoft Visual C++ 
building HelloCE with, 16-18 
SDK tools, 17 
string prefixes, 639 
Microsoft Windows 3.1, 5, 48 
Microsoft Windows 95, 17, 265, 352 
data types and, 5 
desktop connectivity and, 634, 705 
shell programming and, 709-12, 717 
Microsoft Windows 98, 5, 20, 150, 499 
controls and, 265, 296 
desktop connectivity and, 634 
drawing on the screen and, 36, 65-66 
emulators and, 17 
the file API and, 389, 410, 413 
handling bitmaps in, 65-66 
memory management and, 349, 351, 365, 
367, 368 
processes and, 493, 494, 497 
the registry API and, 467, 473 
serial communications and, 546, 555 
shell programming and, 709, 711-12, 
715-16, 726 
Microsoft Windows NT, 3, 20, 150, 265, 380 
desktop connectivity and, 634 
emulators and, 17 
the file API and, 389, 410, 413 
handling bitmaps in, 65-66 
image list control and, 296 
IrSock and, 579, 586 
memory management and, 349, 351-52, 
354, 365, 367-68 
processes and, 493-94, 497 
the registry API and, 469, 473 
serial communications and, 546, 555 
shell programming and, 710, 711-12, 
716, 726 
synchronization and, 507 
threads and, 499, 506 
Unicode-enabled applications for, 5 
Microsoft Word, 681-82. See also Microsoft 
Pocket Word 
MIPS microprocessors, 16 
MM_TEXT mapping mode, 36 
Mobile Devices, 17, 633, 687 
Mobile Devices folder, 17, 633 
modems, indication of, with the PST_MODEM 
flag, 554 
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MONTHCAL_CLASS flag, 319 
month calendar control, 319-21 
MONTHDAYSTATE variable, 320-21 
mouse, 4, 105, 113-14 
drivers, 540 
right-button clicks, 114 
MoveFile function, 412-13 
MS-DOS, 6, 47, 351, 382 
drive letters, 415 
serial communications and, 545, 550 
truncating files in, 386 
MSG structure, 20 
multitasking, preemptive, 515 
Murphy's Law, 515 
mutexes, 507, 509, 513-14, 529-30 
myapp program, 667-68 
MyCreateHatchBrush function, 85 
MyNotify program, 731-42 
MyNotify.c, 732-33, 735-42 
MyNotify.h, 733-35 
window, 732 
MySqurt program, 612-26 
MySqurt.c, 615-26 
MySqurt.h, 613-15 
MySqurt.rc, 612-13 
window, after a file transfer, 672 


navigation keys, 787 

nBottomRect parameter, 76 

nCmdShow parameter, 25 

NETRESOURCE structure, 582, 583, 585-87 

New button, position of, on the command 
bar, 280 

NextConvertFile function, 687-89, 704—5 

NK.EXE, 794-801, 802, 493 

nLeftRect parameter, 76 

NMDAYSTATE structure, 320 

NMHDkR structure, 320 

NMSELCHANGE structure, 321 

nonsignaled state, 508 

NOPARITY constant, 551 

Notepad, 128, 173 

Notification API, 710, 753, 680, 804. See also 
notifications 

notifications. See also messages; Notification 
API 

basic description of, 6-8 


notifications, continued 
of double clicks/taps, 22 
MyNotify program and, 731-42 
shell programming and, 726—42 
Notify button, 726 
NOTIFYICONDATA structure, 717 
NOTIFYICON structure, 718 
nPos field, 168, 169 
NPWnd.c, 780-86 
NPWnd.h, 770-71 
nkeadCnt variable, 530, 531 
nResult parameter, 214 
nRightRect parameter, 76 
nShowCmd parameter, 20, 23 
nStartPage/pStartPage union, 219 
nTopRect parameter, 76 
nTrackPos field, 169 
NULIL_PEN parameter, 72 
NumPanel program 
IM window, in docked/undocked 
positions, 766-67 
input method for, 766-86 
NPWnd.c, 780-86 
NPWnd.h, 770-71 
NumPanel.cpp, 771-80 
NumPanel.def, 767 
NumPanel.h, 768-70 
NumPanel.rc, 768 
nWidth parameter, 64, 72 
nXOrg parameter, 74 
nYOrg parameter, 74 


0 
OAL (OEM Adaptation Layer), 794-95 
objects. See also object store memory 
event, 508-14 
IDs for, 389, 434-35 
information about, querying, 434-35 
memory-mapped, 410-12 
naming, 411-12 
waiting on, 511 
object store memory, 381, 420, 433-34 
basic description of, 350, 379 
opening databases outside of, 423 
system memory queries and, 355 
ODDPARITY constant, 551 
OEMInit routine, 795 
OK button, 218, 223, 583, 584 
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OnCreateMain routine, 61, 147, 261, 318 

OnNotifyMain routine, 294, 465 

OnPaintMain function, 46, 61, 84-85 

OOM (out-of-memory) dialog box, 376, 
725, 726 

opaque mode, 47, 85 

OPEN_ALWAYS flag, 383, 419 

Open button, position of, on the command 
bar, 280 

OpenCreateDB function, 435 

OpenDestinationFile function, 704 

OPEN_EXISTING flag, 383, 419 

OptionsData function, 628 

Options field, 629 

OptionsSize function, 628 

optname parameter, 606 

OS/2, 16, 67 

OSVERSIONINFO structure, 808 

Out of Memory dialog box, 376, 725, 726 

overlapped I/O, 547 

owner/owned relationships, 149-51 


P 


packed format, 74 
paged virtual memory, 351-52 
PAGE_EXECUTE flag, 360 
PAGE_EXECUTE_READ flag, 360 
PAGE_EXECUTE_READWRITE flag, 360 
PAGE_GUARD flag, 361 
PAGE_NOACCESS flag, 361 
PAGE_NOCACHE flag, 361 
PAGE_READONLY flag, 360 
PAGE_READWRITE flag, 360 
Page Setup dialog box, 224 
PAINTINFO structure, 61 
PAINTSTRUCT structure, 29-30 
Palm-size PC 

batteries, 350, 501-2 

boot process and, 801 

Button control panel applet, 789 

Calculator applet, 497 

compile-time versioning and, 804—5 

cross-platform applications and, 803—4 

CtlView program and, 176 

the database API and, 418 

desktop connectivity and, 633, 635, 705 

dialog boxes and, 225, 261, 725, 726 

displaying shapes on, 85 
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Palm-size PC, continued 
File Open dialog box on, 225 
gray-scale displays used by, 207 
group boxes and, 171 
hardware keys, 789-90 
input methods, 766-86 
input panels and, 753, 754, 757 
keyboard input and, 87 
lack of a Close button in, 19 


memory management and, 350, 373-74, 


375-76, 377 
navigation buttons, 787 
new controls for, 5 
Out Of Memory dialog box, 725, 726 
portrait-mode screen, 809 
processes and, 497-98 
running HelloCE on, 18-19, 32, 33 
serial communications and, 557, 577 
shell programming and, 709-13, 728, 
749-55, 757, 700-87, 789-92 
system programming and, 793, 801, 
803-5, 809 
threads and, 501 
parameters 
bErase parameter, 37 
biClrUsed parameter, 67 
bInheritHandle parameter, 498 
bInitialoOwner parameter, 513 
bInitialState parameter, 508 
biSizelmage parameter, 67 
BLACK_PEN parameter, 72 
bManualReset parameter, 508 
buf parameter, 604 
bWaitAll parameter, 511 
cFindData parameter, 642 
cPlanes parameter, 64 
cPropID parameter, 432 
crColor parameter, 72, 73 
dwCreateFlags parameter, 495, 502 
dwDatabaseType parameter, 433 
dwDesiredAccess parameter, 382, 408 
dwFreeType parameter, 362 
dwindex parameter, 472 
dwinfoLevel parameter, 590 
dwinitialSize parameter, 368 
dwloControlCode parameter, 544 
dwMilliseconds parameter, 504, 509 
dwMoveMethod parameter, 385 


dwNumberO/BytesToMap parameter, 409 
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parameters, continued 


dwOffset parameter, 68 
dwOptions parameter, 470 
dwScope parameter, 585 
dwSeekType parameter, 426 
dwShareMode parameter, 382 


dwSize parameter, 359, 362, 363, 420, 762 


dwStack parameter, 502 

dwStackSize parameter, 502 

dwsStyle parameter, 150, 277, 295 

dwValue parameter, 427 

fAllocationType parameter, 360 

flags parameter, 38, 604 

[NewProtect parameter, 363 

JnPenStyle parameter, 72 

fOptions parameter, 368 

{Protect parameter, 360, 408 

[Redraw parameter, 168 

fShow parameter, 279 

fsModifiers parameter, 791 

hPreviInstance parameter, 19 

hSection parameter, 68 

bSrc parameter, 70 

hTemplate parameter, 384 

iButton parameter, 127, 269, 273, 277 

ICmdLine parameter, 19, 20 

idMenu parameter, 269 

idNewltem parameter, 125 

iMaxSockets parameter, 600 

iUsage parameter, 68 

iWidth parameter, 277 

IpAddress parameter, 362, 363, 364 

lpApplicationName parameter, 495 

lParam parameter, 26, 52, 61, 92, 93, 
95, 106, 114, 123, 125, 127, 151, 166, 
172-73, 212, 216, 221-23, 298, 274, 
276, 717, 758, 792 

IpBuffer parameter, 132, 273, 385, 586, 
587, 590 

IpBytesReturned parameter, 544 

IpCmdline parameter, 497 

IpCommandLine parameter, 495 

IpcPropID parameter, 430 

IpData parameter, 470 

IpEventAttributes parameter, 508 

IpHandles parameter, 511 

IpLibFileName parameter, 805 

IpName parameter, 409, 508, 513 

IpNetResource parameter, 582, 585 


parameters, continued 
IpNewltem parameter, 126 
IpnLength parameter, 589, 591 
lpOutBuffer parameter, 544 
lpOverlapped parameter, 384, 385, 548 
lpParameter parameter, 502 
IpProcessInformation parameter, 496 
IpRect parameter, 37 
IpSecurityAttributes parameter, 382, 470 
IpszClassName parameter, 23 
IpszName parameter, 424 
IpszNewltem parameter, 125 
IpszValueName parameter, 470 
lpThreadAttributes parameter, 502 
IpTime parameter, 727, 730 
lpToolTips parameter, 278 
IpType parameter, 470 
IpUserName parameter, 591 
nBottomRect parameter, 76 
nCmdShow parameter, 25 
nLeftRect parameter, 76 
nResult parameter, 214 
nRightRect parameter, 76 
nShowCmd parameter, 20, 23 
nTopRect parameter, 76 
NULL_PEN parameter, 72 
nWidth parameter, 64, 72 
nXOrg parameter, 74 
nYOrg parameter, 74 
optname parameter, 606 
pbkResult parameter, 470 
pPIRAPIStream parameter, 649, 652 
DpvBits parameter, 68 
RequestData parameter, 627 
RequestOptions parameter, 628 
RequestSize parameter, 627 
Reserved parameter, 470 
shutdown parameter, 605 
szCmdline parameter, 497 
uiAction parameter, 750-51 
uNumToolTips parameter, 278 
wParam parameter, 21, 26, 31-32, 
88-89, 92, 95, 97, 106, 114, 127, 130, 
166, 169-70, 172, 221, 717, 755, 757 
parent/child windows, 6, 149 
basic description of, 150-69 
enumerating, 151 
finding, 151, 152 
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Pascal, 26 
PC/AT CBM), 793 
PC Cards, 381, 386, 415 
PCI bus, 540 
PC Magazine, 16 
PCMCIA cards, 539, 542, 577, 798 
pcRefCount field, 221 
pens, 72, 75. See also PenTrac program 
PenTrac program 
PenTrac.h, 108 
PenTrac.c, 109-13 
window, showing two lines drawn, 107 
Petzold, Charles, 15, 86 
pfnCallBack field, 220, 221 
DfnDigProc field, 221 
DbkResult parameter, 470 
pidl, 711, 713 
PingAddress function, 629 
PIRAPIStream parameter, 649, 652 
pixels, 4, 63, 64, 71-72 
PMEMORY_BASIC_INFORMATION 
structure, 363 
Pocket Word. See Microsoft Pocket Word 
pointer data type, 15 
POINT structures, 71 
polygons, 73, 76-77 
PostQuitMessage function, 21, 32, 147 
power supplies, 501, 801-2. See also batteries 
ppsp/phpage union, 219 
DpvBits parameter, 68 
Print button, position of, on the command 
bar, 280 
Print dialog box, 150, 208, 224, 261 
printf function, 742 
priority classes, 499 
private memory pages, 356-57 
procedures 
BtnWndProc procedure, 206-7 
DoActivateMain procedure, 31-32 
DoHibernateMain procedure, 30-31 
FindClose procedure, 413, 414, 415 
FindFirstFile procedure, 413-15, 433, 581 
FindNextFile procedure, 414, 433, 581 
FindNext procedure, 413 
InitApp procedure, 14, 20, 21-23, 261 
InitInstance procedure, 20, 23-25, 528 
MainWndProc procedure, 25-27 
ScrollWndProc procedure, 207 
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procedures, continued 
window procedure, 6-7, 16 


WinMain procedure, 16, 19, 23, 25-26, 32, 


497, 645, 649, 742, 744 

WinProc procedure, 16 
processes. See also threads 

basic description of, 493-536 

creating, 494-97 

finding other, 516-18 

terminating, 497-98, 503 

waiting on, 510-11 


PROCESS_INFORMATION structure, 496, 497 


PROCESSOR_ARCHITECTURE_INTEL 
constant, 354 

PROCESSOR_ARCHITECTURE_SHx 
constant, 354 


PROCESSOR_HITACHI_SH3 constant, 354 
PROCESSOR_HITACHI_SH4 constant, 354 


processors, 794, 801 
exception handling and, 534 


memory management and, 351-52, 354, 


356, 305, 373-74 
that support Windows CE, 3 


system programming and, 793-94, 801 


target, selecting, 16 
threads and, 499, 501 
program memory, 350 


Programming Windows 95 (Petzold), 3, 


15, 86 
programs 
AlbumDB program, 435-67 


Calc program, 497, 715-16, 800, 801 


CeChat program, 560-77 
CEFind program, 743-47 
CmdBand program, 304-19 
CmdBar program, 280-94 
CnctNote program, 671-80 
CtlView program, 176-208, 261 
DivFile program, 691-705 
DlgDemo program, 226-61 
FileView program, 389-407 
FontList2 program, 153-69 
FontList program, 53-62 
HelloCE program, 3—21, 32-33 
KeyTrac program, 95-105 
ListNet program, 591-99 
LView program, 326-46 
myapp program, 667-68 
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programs, continued 
MyNotify program, 731-42 
MySqurt program, 612-26 
RapiDir program, 644-48 
RapiFind program, 653-62 
Shapes program, 77-86 
TBlIcons program, 718-25 
TextDemo program, 40-47 
TicTacl program, 114-25 
TicTac2 program, 133-47 
XTalk program, 518-31 

Programs submenu, 715-16 

Project Settings dialog box, 18 


properties. See also property pages; property 


sheets 
deleting, 432-33 
IDs for, 422, 428 
property pages, 218, 220-24 
PropertySheet function, 218, 219 
property sheets, 149, 218-24, 226 
PROPSHEETHEADER structure, 218 
PROPSHEETPAGE structure, 219, 220, 
222, 261 
Protect field, 363, 365 
PSH_MODELESS flag, 219 
PSH_PROPSHEETPAGE flag, 219 
PSH_PROPTITLE flag, 219 
PSH_USEPSTARTPAGE flag, 219 
PSM_ADDPAGE message, 221 
PSM_REMOVEPAGE message, 221 


_PSN_KILLACTIVE message, 223 


PSP_DLGINDIRECT flag, 220 
PSP_PREMATUERE flag, 221-22 
PSP_USECALLBACK flag, 220-21 
PSP_USEREFPARENT flag, 221 
PSP_USETITLE flag, 221 
PST_MODEM flag, 554 
pszTemplate/pResource union, 220 
PTS file type, 692 
PURGE_RXABORT flag, 555 
PURGE_RXCLEAR flag, 554-55 
PURGE_TXABORT flag, 555 
PURGE_TXCLEAR flag, 554 

push buttons, 170, 207 

push models, 6 

PWD (Pocket Word) format, 681, 683 


0 
QS_ALLINPUT flag, 512 
OS_INPUT flag, 512 
QOS_KEY flag, 512 
QS_MOUSEBUTTON flag, 512 
QS_MOUSE flag, 512 
QS_MOUSEMOVE flag, 512 
QS_PAINT flag, 512 
QS_POSTMESSAGE flag, 512 
QS_SENDMESSAGE flag, 512 
QS_TIMER flag, 512 
quantum (time slice), 499, 504-5 
querying 
connections, 589-91 
device driver capabilities, 553-54 
database object information, 434-35 
file size information, 388, 407, 639 
memory access rights, 363-05 
memory heaps, 366-67, 369 
resources, 589-91 
status, clearing, 555-56 
system memory, 354-56 
thread priority, 504 
question mark (?), 413 


radio buttons, 171, 207 


RAM (random access memory), 174, 355, 380. 


See also memory; object store memory 
basic description of, 350 
command bars and, 279 
constant data and, 27 
list boxes and, 174 
power supplies and, 801 
requirements, 349 
ROM and, 350-51 
threads and, 501 
virtual, 4, 351 
RAPI (Windows CE Remote API) 
basic description of, 633-62 
custom functions, 648-53 
dealing with different versions of, 635 
predefined functions, 637-44 
RapiDir program, 644-48 
RAPI.DLL, 635, 667 
RapiFind program, 653-62 
output, 654 
RapiFind.cpp, 659-62 


index 


RapiServ.c, 649-51 
raw IR, 557-59, 576 
RBBIM_CHILDSIZE style flag, 298 
RBBIM_CHILD style flag, 298 
RBBIM_COLORS style flag, 298 
RBBIM_IDEALSIZE style flag, 298 
RBBIM_ID style flag, 298 
RBBIM_LPARAM style flag, 298 
RBBS_BREAK style flag, 297 
RBBS_CHILDEDGE style flag, 297 
RBBS_FIXEDBMP style flag, 297 
RBBS_FIXEDSIZE style flag, 297 
RBBS_GRIPPERALWAYS style flag, 297 
RBBS_HIDDEN style flag, 297 
RBBS_NOGRIPPER style flag, 297, 300, 318 
RBBS_NOVERT style flag, 297-98 
RBBS_RBBIM_STYLE style flag, 297 
RBS_AUTOSIZE style flag, 295 
RBS_BANDBORDERS style flag, 295 
RBS_FIXEDORDER style flag, 295 
RBS_SMARTLABELS style flag, 295, 298, 
300, 318 
RBS_VARHEIGHT style flag, 295, 300 
RBS_VERTICALGRIPPER style flag, 295 
RCDATA resource type, 129 
rcPaint field, 30 
rcSipRect field, 752, 761, 762 
rcVisibleDesktop function, 752 
ReadDonekvent function, 529 
ReadDone function, 530 
ReaderThread function, 528, 530, 531 
ReadkEvent function, 529, 530, 531 
ReadFile function, 382, 384-85, 407, 544, 
540-47, 551, 552 
ReadIntervalTimeout function, 551, 552 
read-only mode, 409 
ReadTotalTimeoutConstant function, 551 
ReadTotalTimeoutMultiplier function, 551 
REBARBANDINFO structure, 296-97, 
299-300, 318 
ReceiveSipInf method, 760, 762 
recent documents list/submenu, 716 
records 
basic description of, 417-19 
deleting, 432-33 
reading, 429-32 
searching for, 426-29 
writing, 432 
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Rectangle function, 73, 74, 75 
rectangles, 46, 74-76, 85 
clipping, 62 
expanded view of, drawn with the 
Rectangle function, 75 
RECT structure for, 29, 30 
for the TicTacl program, 124—25 
recv function, 601 
RegCreateKeyEx function, 470 
RegEnumKeyEx function, 472-73 
RegisterCallback method, 760, 762 
RegisterClass function, 22, 23, 152 
registry, 495, 581, 663-68. See also registry 
keys 
API, 379, 467-91 
boot process and, 796, 798, 799, 600 
deleting values in, 471-72 
device driver documentation, 540, 547, 
542-43, 558, 559 
management functions, 643 
method, of connection notification, 667-69 
organization of, 468-69 
reading/writing values in, 302, 470, 471, 
666-67 
registering file filters in, 681-86 
RegView program and, 473-91 
registry keys. See also registry; registry keys 
Cisted by name) 
application launch keys, 788, 789-92 
closing, 472 
deleting, 471-72 
enumerating, 472—73 
hardware keys, 787-92 
opening/creating, 469-70 
for the Wave driver on an HP360, 798 
registry keys (listed by name). See also 
registry keys 
CESVC_CUSTOM_MENUS key, 663 
CESVC_DEVICE_SELECTED key, 664 
CESVC_DEVICES key, 663, 664 
CESVC_DEVICEX key, 664 
CESVC_FILTERS key, 663, 664 
CESVC_ROOT_MACHINE key, 663, 668 
CESVC_ROOT_USER key, 663 
CESVC_SERVICES_COMMON key, 663 
CESVC_SERVICES_USER key, 664 
CESVC_SYNC_COMMON key, 663 
CESVC_SYNC key, 664 


846 


registry keys (listed by name), continued 
HKEY_CLASSES_ROOT key, 468, 681, 682 
_ HKEY_CURRENT_USER key, 468, 663, 681 
HKEY_LOCAL_MACHINE key, 468, 469, 
495, 540-42, 558, 581, 663, 681, 682, 686, 
789, 796, 798, 800 
RegOpenKeyEx function, 469-70 
RegQueryValueEx function, 470 
RegView program 
RegView.c, 476-91 
RegView.h, 474-76 
RegView.rc, 473-74 
ReleaseCapture function, 113 
ReleaseDC function, 38, 70 
Release method, 714 
ReleaseMutex function, 514, 529 
remote 
drives, mapping, 581-83 
resources, disconnecting, 583-84 
RemoveDirectory function, 412 
report mode, 324-25 
RequestData parameter, 627 
RequestOptions parameter, 628 
RequestSize parameter, 627 
Reserved field, 93 
reserved memory pages, 352, 356-57 
Reserved parameter, 470 
ResetEvent function, 509 
RESOURCE_CONNECTED flag, 585 
RESOURCE_GLOBALNET flag, 585, 586 
RESOURCE_REMEMBERED flag, 585 
resources 
basic description of, 127-32 
creating, 128 
fewer, in Windows CE devices, 4 
enumerated, 585-69 
querying, 589-91 
remote, disconnecting, 583-84 
types of, allowed by the resource 
compiler, 729 
ResumeCount function, 504 
ResumeThread function, 502, 504 
RGB color, 66-68, 72—74, 172-73 
RGB macro, 72-73 
Richter, Jeff, 377 
right-clicking, 4 
RLSD (Receive Line Signal Detect) line, 
548, 556 


ROM (read only memory), 27, 174, 805 
basic description of, 350-51 
boot process and, 795 
the file API and, 380, 387 
files, compressed, 387 
static data and, 371, 374 
ROM-based DLLs, 379-80 
RoundRect function, 73, 76 
RoundTripTime field, 629 
RS-232 serial ports, 554. See also serial ports 
RTS line, 550, 555 
run-time version checking, 808-9 


3 
Save As dialog box, 224 
Save button, position of, on the command 
bar, 280 
SB BOTTOM code, 167 
SB_CTL code, 168 
SB_HORZ code, 168 
SB_LINEDOWN code, 166, 167 
SB_LINELEFT code, 166, 167 
SB_LINERIGHT code, 166, 167 
SB_LINEUP code, 166, 167 
SB_PAGEDOWN code, 166, 167 
SB_PAGELEFT code, 166, 167 
SB_PAGERIGHT code, 166, 167 
SB_PAGEUP code, 166, 167 
SB_THUMBPOSITION code, 166, 167, 168 
SB_THUMBTRACK code, 166, 167, 168 
SB_TOP code, 167 
SB_VERT code, 168 
screens, 4-5, 35-87, 95, 105-25, 809 
scroll bars, 63, 153-70, 175 
codes for, 166, 167 
configuring, 168-69 
in the FontList window, 62 
hot spots for, 766 
positioning, beneath command bars, 153, 
154-69 
ScrollDlg.c, 257-60 
SCROLLINFO structure, 168, 169 
ScrollWnd.c, 201-5 
ScrollWndProc procedure, 207 
SDK (Windows CE Software Development 
Kit), 544, 548, 627 
security, 356-57, 363-65, 380, 409 
select function, 610, 611 
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Select method, 759, 761 
SelectObject function, 51, 62, 69 
semaphores, 507 
Send button, 518, 529 
SendCharEvents function, 764, 765-66 
SenderThread function, 528, 530, 531 
send function, 601, 605 
SendMessage function, 130, 267 
SendString function, 764, 766 
SendVirtualKey function, 763, 765 
serial communications. See also device 
drivers; infrared transmissions; serial 
ports 
basic description of, 539-78 
CeChat program and, 560-77 
configuring serial ports for, 548-51 
setting timeout values for, 551-52 
serial ports. See also serial communications 
programming, 545-57 
reaching to, 546-47 
setting timeout values for, 551-52 
writing to, 546-47 
server functions, writing, 649-52 
SETBREAK flag, 555 
SetCommBreak function, 554, 555 
SetCommsState function, 548-49, 551 
SetFilePointer function, 385, 407 
SetImData method, 760, 762-63 
SetImInfo function, 763-65 
SetScrollinfo function, 168, 169, 175 
SetupComm function, 552 
SetWindowLong function, 152, 224 
SETXOFF flag, 555 
SETXON flag, 555 
shapes, 71, 73-86. See also Shapes program 
polygons, 73, 76-77 
rectangles, 29-30, 46, 62, 74-76, 85, 124-25 
Shapes program, 77-86. See also shapes 
Shapes.c, 78-84 
shapes.h, 77-78 
window, 8&5 
shortcuts, 715 
Showing method, 760 
ShowWindow function, 20, 25 
SHSipInfo function, 750-53, 755, 756, 762, 805 
shutdown parameter, 605 
SIF_DISABLENOSCROLL flag, 169 
SIF_PAGE flag, 169 
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SIF_POS flag, 168 
SIF_RANGE flag, 168 
SIF_TRACKPOS flag, 169 
signaled state, 508 
SignalStarted function, 797 
Simonyi, Charles, 15. 
SIMPLE.DLL, 806 
SIP (Supplementary Input Panel), 749-59, 
766-92, 803-4 
components of, 758-59 
explicit linking and, 806 
hardware keys and, 787-92 
SIPF_DOCKED flag, 751 
SIPF_LOCKED flag, 751 
SIPF_ON flag, 751 
SIPINFO structure, 751, 752, 753, 756, 763 
_ SipkegisterNotification function, 757 
slash (/)), 128 
sleep function, 107, 504—5 
slots, memory, 352 
SOCKADDR structure, 602 
sockets, 602-5, 609-12 
Software Development Kit (Windows CE), 
544, 548, 627 
sort orders, 422-23, 429 
SORTORDERSPEC structure, 422 
SPACEPARITY constant, 551 
SrchDirectory function, 658-59, 744 
Start button, 63, 149, 709 
Start menu, configuring, 715-16 
State field, 363, 365 
Static control class, 170, 175 
StaticDlg.c, 255-57 
Status field, 629 
StatWnd.c, 199-201 
STILL_ACTIVE constant, 497 
StopBits field, 551 
Storage Card, 415 
stream mode, 652-53 
strikeout font, 49 
strings, 5, 373 
converting, 24, 639, 648 
data type for, 15 
lists of, defining, 129 
Unicode, 24, 39, 132, 542, 648 
STRINGTABLE resource type, 129 
struct data type, 15 
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BITMAPINFOHEADER structure, 66-67 
BITMAPINFO structure, 66, 74 
BY_HANDLE_FILE_INFORMATION 
structure, 388—89 
CEDBASEINFO structure, 423, 429, 435 
CEFILEINFO structure, 434-35 
CE_FIND_DATA structure, 640-41, 648 
CEIODINFO structure, 434 
CENOTIFICATION structure, 425, 426 
CENOTIFYREQUEST structure, 425, 426 
CEPROPID structure, 430, 432 
CEPROPVAL structure, 427, 432 
COMMANDBANDRESTOREINFO structure, 
301-3 
COMMPROPFP structure, 553 
COMMTIMEOUTS structure, 551, 552 
COMSTAT structure, 556 
CONNECTDLGSTRUCT structure, 583 
CREATESTRUCT structure, 125 
CRITICAL_SECTION structure, 514 
DEVICELIST structure, 606 
DLGTEMPLATE structure, 212 
DRAWITEMSTRUCT structure, 172 
FILETIME structure, 387, 388 
ICMP_ECHO_REPLY structure, 628-31 
IMENUMINFO structure, 756 
IMINFO structure, 760-61 
IRDA_DEVICE_INFO structure, 606 
LOGFONT structure, 48, 49, 51, 53 
LOGPEN structure, 72 
MEMORYSTATUS structure, 355 
MSG structure, 20 
NETRESOURCE structure, 582, 583, 585-87 
NMDAYSTATE structure, 320 
NMHDR structure, 320 
NMSELCHANGE structure, 321 
NOTIFYICONDATA structure, 717 
NOTIFYICON structure, 718 
OSVERSIONINFO structure, 808 
PAINTINFO structure, 61 
PAINTSTRUCT structure, 29-30 
PMEMORY_BASIC_INFORMATION 
structure, 363 
PROCESS_INFORMATION structure, 
496, 497 
PROPSHEETHEADER structure, 218 


structures, continued 
PROPSHEETPAGE structure, 219, 220, 
222, 261 
REBARBANDINFO structure, 296-97, 
299-300, 318 
SCROLLINFO structure, 168, 169 
SIPINFO structure, 751, 752, 753, 756, 763 
SOCKADDR structure, 602 
SORTORDERSPEC structure, 422 
SYSTEMTIME structure, 320, 727, 730 
TBBUTTON structure, 273 
TBUTTON structure, 272 
TEXTMETRIC structure, 50-51, 62 
TIMEVAL structure, 610 
TPMPARAMS structure, 277 
WINDCLASS structure, 152 
WNDCLASS structure, 22—24 
WSAData structure, 599 
style flags. See also flags; styles 
BS_2STATE style flag, 171 
BS_AUTO2STATE style flag, 171 
BS_AUTOSSTATE style flag, 206 
BS_AUTOCHECKBOxX style flag, 171, 206 
BS_AUTORADIOBUTTON style flag, 
171, 206 
BS_BOTTOM style flag, 171 
BS_CHECKBOxX style flag, 171 
BS_ICON style flag, 172 
BS_LEFT style flag, 171 
BS_MULTILINE style flag, 171 
BS_OWNERDRAW style flag, 172 
BS_RADIOBUTTON style flag, 171 
BS_RIGHT style flag, 171 
BS_TOP style flag, 171 
CCS_VERT style flag, 295 
DS_ABSALIGN style flag, 209 
DS_CENTER style flag, 209 
DS_MODALFRAME style flag, 209 
DS_SETFONT style flag, 210 
DS_SETFOREGROUND style flag, 210 
DTS_APPCANPARSE style flag, 322 
DTS_IC_DATE_CLASSES style flag, 322 
DTS_LONGDATEFORMAT style flag, 322 
DTS_SHORTDATEFORMAT style flag, 322 
DTS_SHOWNONE style flag, 322 
DTS_TIMEFORMAT style flag, 322 
DTS_UPDOWN style flag, 322 
ES_LOWERCASE style flag, 173 
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style flags, continued 


ES_MULTILINE style flag, 173 
ES_PASSWORD style flag, 173 
ES_READONLY style flag, 173 
ES_UPPERCASE style flag, 173 
GWL_EXSTYLE style flag, 152 
GWL_ID style flag, 152 
GWL_STYLE style flag, 152 
GWL_USERDATA style flag, 152 
GWL_WNDPROC style flag, 152 
LPTR flag, 366 
LVM_GETTEXTENDEDLISTVIEWSTYLE 
style flag, 324 
LVM_INSERTITEM style flag, 267 
LVM_SETTEXTENDEDLISTVIEWSTYLE 
style flag, 324 
LVN_GETDISPINFO style flag, 325, 465 
LVN_ODCACHEHINT style flag, 325-26 
LVN_ODFINDITEM style flag, 325 
LVS_AUTOARRANGE style flag, 325 
LVS_EX_CHECKBOXES style flag, 324, 325 
LVS_EX_FLATSB style flag, 325 
LVS_EX_GRIDLINES style flag, 325 
LVS_EX_HEADERDRAGDROP style 
flag, 324 
LVS_EX_INFOTIP style flag, 325 
LVS_EX_ONECLICKACTIVATE style 
flag, 325 
LVS_EX_REGIONAL style flag, 325 
LVS_EX_SUBITEMIMAGES style flag, 325 
LVS_EX_TRACKSELECT style flag, 325 
LVS_EX_TWOCLICKACTIVATE style 
flag, 325 
LVS_FULLROWSELECT style flag, 325 
LVS_OWNERDATA style flag, 324, 325 
LVS_SETITEMPOSITION style flag, 325 
LVS_SORTASCENDING style flag, 325 
LVS_SORTDESCENDING style flag, 325 
RBBIM_CHILDSIZE style flag, 298 
RBBIM_CHILD style flag, 298 
RBBIM_COLORS style flag, 298 
RBBIM_IDEALSIZE style flag, 298 
RBBIM_ID style flag, 298 
RBBIM_LPARAM style flag, 298 
RBBS_BREAK style flag, 297 
RBBS_CHILDEDGE style flag, 297 
RBBS_FIXEDBMP style flag, 297 
RBBS_FIXEDSIZE style flag, 297 
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style flags, continued 
RBBS_GRIPPERALWAYS style flag, 297 
RBBS_HIDDEN style flag, 297 


RBBS_NOGRIPPER style flag, 297, 300, 318 


RBBS_NOVERT style flag, 297-98 
RBBS_RBBIM_STYLE style flag, 297 
RBS_AUTOSIZE style flag, 295 
RBS_BANDBORDERS style flag, 295 
RBS_FIXEDORDER style flag, 295 
RBS_SMARTLABELS style flag, 295, 298, 
300, 318 
RBS_VARHEIGHT style flag, 295, 300 
RBS_VERTICALGRIPPER style flag, 295 
WS_CAPTION style flag, 209, 210 
WS_CHILD style flag, 150, 165, 278 
WS_EX_CAPTIONOKBTN style flag, 210 
WS_EX_CONTEXTHELLP style flag, 210 
WS_GROUP style flag, 211 
WS_HSCROLL style flag, 167 
WS_OVERLAPPED style flag, 150 
WS_POPUP style flag, 210 
WS_SYSMENU style flag, 209, 210 
WS_TABSTOP style flag, 211 
WS_VISIBLE style flag, 24, 150, 165, 205, 
278, 374 
WS_VSCROLL style flag, 165, 167 
styles. See also style flags 
extended, 324 
new, in report mode, 324-25 — 
stylus, 87, 95, 105-25 
SuspendThread function, 504 
synchronization, 507-16, 635 
System control panel applet, 350 
system event notifications, 730-31 
system programming 
basic description of, 793-810 
cross-platform applications and, 802-9 
system configuration, 802 
System Scheduler, 499-501 
SYSTEMTIME structure, 320, 727, 730 
szCmdline parameter, 497 
szDatabaseName field, 423 
szDescription field, 600 
szFullPath field, 689 
szSystemStatus field, 600 
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T 
TabbedTextOut function, 62 
taskbar, 149-50, 726-27, 757 

boot process and, 800-801 

interface, 716-25 

SIP configuration and, 751 
Tasks database, 421 
TBBUTTON structure, 273 
TBIcons program, 718-25 

TBlIcons.c, 721-25 

TBlicons.h, 719-20 

TBIcons.rc, 719 

window, 718 
TBSTATE_AUTOSIZE flag, 273 
TBSTATE_BUTTON flag, 273 
TBSTATE_CHECKED flag, 272 
TBSTATE_CHECK flag, 273 
TBSTATE_CHECKGROUP flag, 273 
TBSTATE_DROPDOWN flag, 273 
TBSTATE_ENABLED flag, 272 
TBSTATE_GROUP flag, 273 
TBSTATE_HIDDEN flag, 272 
TBSTATE_INDETERMINATE flag, 272 
TBSTATE_PRESSED flag, 272 
TBSTATE_SEP flag, 273 
TBSTATE_WRAP flag, 272 
TBUTTON structure, 272 
TCHAR data type, 5 
TCP/IP (Transmission Control Protocol/ 


Internet Protocol), 557, 579, 602—5, 608, 


626-31 

templates, 128-29, 209-10, 214-16 
TerminateProcess function, 498 
terminating 

processes, 497-98, 503 

programs, 32 
TermInstance function, 21, 32 
text. See also fonts 

alignment, 175 

color, 47 

letters of, space between, 40 
TextDemo program, 40-47 

TextDemo.c, 42—46, 51 

TextDemo.h, 41-42 
TEXT macro, 24, 39, 639 
TEXTMETRIC structure, 50-51, 62 


THREAD_ABOVE_IDLE priority level, 500 
THREAD_ABOVE_NORMAL priority 
level, 500 
THREAD_BELOW_NORMAL priority 
level, 500 
THREAD_HIGHEST priority level, 500 
THREAD_IDLE priority level, 500 
THREAD_LOWEST priority level, 500 
THREAD_NORMAL priority level, 500 
THREAD_PRIORITY_IDLE priority level, 504 
THREAD_PRIORITY_NORMAL priority level, 
501, 504 
THREAD_PRIORITY_TIME_CRITICAL priority 
level, 504 
threads, 493-536, 547, 552. See also processes 
blocked, 500 
creating, 502-5 
local storage, 505-7 
priority classes for, 499-501, 504 
suspending/resuming, 504—5 
synchronization and, 507-16 
waiting on, 510-11 
THREAD_TIME_CRITICAL priority level, 500 
throw keyword, 531 
TicTacl program, 114-25 
TicTacl.c, 116-24 
TicTacl.h, 115-16 
window, 115 
TicTac2 program, 133-47 
TicTac2.c, 136—47 
TicTac2.h, 134-36 
TicTac2.rc, 133-34 
timeout values, 551-52, 628 
timer event notifications, 730 
time slice (quantum), 499, 504—5 
TIMEVAL structure, 610 
TisAlloc function, 506—7 
tmAscent field, 51 
tmDescent field, 51 
tmExternalLeading field, 51, 62 
tmHeight field, 51, 62 
tmInternalLeading field, 51 
ToolHelp, 517 
Tools menu, position of, on the command 
bar, 280 
tool tips, for command bars, 278 
top-level windows, 150 
TPMPARAMS structure, 277 
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TranslateMessage function, 20—21, 132, 217 
TransmitCommcChar function, 547, 556 
transparent mode, 47, 85 

TrueType fonts, 47-50, 743. See also fonts 
TRUNCATE_EXISTING flag, 383, 419 

__try block, 531 

__try, __except block, 532-34 

__try, finally block, 531, 534-36 

TTL (Time-To-Live) values, 628 

Type field, 363, 365 


U 
uiAction parameter, 750-51 
UNC (Universal Naming Convention), 580-81, 
587, 589, 590 
Underline button, position of, on the 
command bar, 280 
Undo menu item, 147 
Unicode, 14, 19, 576, 629 
ASCII versus, 4, 600 
basic description of, 4-5 
data type, 417 
strings, 24, 39, 132, 542, 648 
UNIX, 6 
unnamed memory-mapped objects, 410-11 
uNumToolTips parameter, 278 
Update Remote File command, 19 
User, 36, 358 
user notifications, 726—30 
UTC (universal time format), 387-88 


V 
ValidateRect function, 37 
variables. See also specific variables 
access to, interlocked, 515-16 
Hungarian notation prefixes for, 15 
version 
checking, run-time, 808-9 
problem, 803-5 
VERSIONINFO resource type, 129 
Viewer program 
Viewer.c, 399-407 
Viewer.h, 399 
View menu 
Command Bar command, 304 
position of, on the command bar, 280 
VIRTKEY command, 131 
VirtualAlloc function, 359, 361-62, 364 
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VirtualFree function, 359, 362 
virtual key codes, 89-91, 788-89 
virtual list view mode, 325-26 
virtual memory, 4, 373, 794 

API, 354, 361 


basic description of, 351-52, 359-65 
memory-mapped objects and, 410-11 


reserved, that has nine pages 
committed, 364 

VirtualProject function, 363 
VirtualQuery function, 363, 364, 365 
VirtualReSize function, 359 
Visual C++. See Microsoft Visual C++ 
VK_O—VK_9 constants, 90 
VK_A-VK_Z constants, 90 
VK_ADD constant, 91 
VK_APOSTROPHE constant, 91 
VK_APPS constant, 91 
VK_ATIN constant, 92 
VK_BACK constant, 89 
VK_BACKQUOTE constant, 91 
VK_BACKSLASH constant, 91 
VK_CANCEL constant, 89 
VK_CAPITAL constant, 90 
VK_CLEAR constant, 89 
VK_COMMA constant, 91 
VK_CONTROL constant, 90 
VK_CRSEL constant, 92 
VK_DECIMAL constant, 91 
VK_DELETE constant, 90 
VK_DIVIDE constant, 91 
VK_DOWN constant, 90 
VK_END constant, 90 
VK_EQUAL constant, 91 
VK_EREOF constant, 92 
VK_ESCAPE constant, 90 
VK_EXECUTE constant, 90 
VK_EXESEL constant, 92 
VK_F1—VK_F24 constants, 91 
VK_HELP constant, 90 
VK_HOME constant, 90 
VK_HYPHEN constant, 91 
VK_INSERT constant, 90 
VK_LBRACKET constant, 91 
VK_LBUTTON constant, 89, 94 
VK_LCONTROL constant, 91 
VK_LEFT constant, 90 
VK_LMENU constant, 91 
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VK_LSHIFT constant, 91 
VK_LWIN constant, 90, 788 
VK_MENU constant, 90, 94 
VK_MULTIPLY constant, 91 
VK_NEXT constant, 90 
VK_NONAME constant, 92 
VK_NUMLOCK constant, 91 
VK_NUMPADO-9 constants, 91 
VK_OEM_CLEAR constant, 92 
VK_OFF constant, 92 
VK_PA1 constant, 92 
VK_PERIOD constant, 91 
VK_PLAY constant, 92 
VK_PRIOR constant, 90 
VK_RBRACKET constant, 91 
VK_RBUTTON constant, 89 
VK_RCONTROL constant, 91 
VK_RETURN constant, 90 
VK_RIGHT constant, 90 
VK_RMENU constant, 91 
VK_RSHIFT constant, 91 
VK_SCROLL constant, 91 
VK_SELECT constant, 90 
VK_SEMICOLON constant, 91 
VK_SEPARATOR constant, 91 
VK_SHIFT constant, 90 
VK_SLASH constant, 91 
VK_SNAPSHOT constant, 90 
VK_SPACE constant, 90 
VK_SUBTRACT constant, 91 
VK_TAB constant, 89 

VK_UP constant, 90 
VK_ZONE constant, 92 
volumes, database, 418-20, 465-67 


W 

WaitCommEvent function, 547, 548, 551 

WaitForMultipleObjects function, 509, 511, 
512, 531 

WaitForSingleObjects function, 509-11, 529 

waiting, 509-14 

WAV files, 413, 540 

WINBASE.H, 514, 534, 549, 553 

WINDCLASS structure, 152 

window class, 6, 22, 28 

window handle data type, 15 

window procedure, 6-7, 16 


windows 
basic description of, 149-50 
enumerating, 151 
finding, 151, 152 
iterating through a series of, 151 
management functions for, 151-63 
sizing, 29 
structure values for, editing, 152-53 
valid/invalid regions of, 30, 37 
Windows 3.1. See Microsoft Windows 3.1 
Windows 95. See Microsoft Windows 95 
Windows 98. See Microsoft Windows 98 
Windows CE Services, 662-706 
Windows.h, 14 
Windows NT. See Microsoft Windows NT 
WinMain procedure, 16, 19, 23, 25-26, 32, 
497, 645, 649, 742, 744 
WinProc procedure, 16 
WinSock (socket APD, 599-626 
WINSOCK.H, 610 
WM_ACTIVATE message, 31 
WM_CAPTURECHANGED message, 114 
WM_CHAR message, 89, 92, 97, 750, 764, 765, 
788 
WM_CLOSE message, 147, 497, 498, 792 
WM_COMMAND message, 127, 129, 131, 147, 
170, 176-75, 205-7, 214, 216, 223, 226, 
260-61, 267, 273, 275, 277-79, 530 
WM_COPYDATA message, 517-18 
WM_CREATE message, 7, 25, 27, 31, 61, 125, 
165, 205, 213 
WM_DBNOTIFICATION message, 425, 426 
WM_DEADCHAR message, 93 
WM_DESTROY message, 32, 147 
WM_DRAWITEM message, 172, 206-7 
WM_HIBERNATE message, 30-31, 150, 
374-77 
WM_HSCROLL message, 169, 175, 207 
WM_INITDIALOG message, 213, 216, 
222, 261 | 
WM_KEYDOWN message, 88-89, 92, 97, 750, 
764, 788 
WM_KEYUP message, 89, 92, 97, 750, 
764, 788 
WM_LBUTTONDOWN message, 105-6, 
107, 717 
WM_LBUTTONUP message, 106, 123, 717 
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WM_MOUSEMOVE message, 106, 107, 113 

WM_MOVE message, 7, 8 

WM_NOTIFY message, 223, 224, 226, 260, 
267, 275, 303, 320, 4605, 491 

WM_PAINT message, 25, 28, 29, 30, 36, 37, 
38, 61, 104, 166, 214, 407 

WM_QUIT messages, 21, 32 

WM_RBUTTONDOWN message, 114 

WM_RBUTTONUP message, 114 

WM_SETFOCUS message, 88 

WM_SETTINGCHANGE message, 322 

WM_SIZE message, 123, 679 

WM_SYSCHAR message, 89, 92 

WM_SYSKEYDOWN message, 89 

WM_SYSKEYUP message, 89 

WM_VSCROLL message, 166, 169, 175, 207 

WNDCLASS structure, 22-24 

WNet functions, 580-91 

Word. See Microsoft Word 

word data type, 15 

WorkerBee routine, 505-6 

wPacketLength field, 553 

wPacketVersion field, 553 

wParam parameter, 21, 26, 31-32, 88-89, 92, 
95, 97, 106, 114, 127, 130, 166, 169-70, 
172,221; 7A, 759,957 

WriteFile function, 382, 384, 544, 546-47, 
551-52, 556, 577 

Write method, 659 

WSAData structure, 599 

WSAGetLastError function, 600, 602, 604, 610 

WSAStartup function, 599-600 

WS_CAPTION style flag, 209, 210 

WS_CHILD style flag, 150, 165, 278 

WS_EX_CAPTIONOKBTN style flag, 210 

WS_EX_CONTEXTHELP style flag, 210 

WS_GROUP style flag, 211 

WS_HSCROLL style flag, 167 

WS_OVERLAPPED style flag, 150 

WS_POPUP style flag, 210 

WS_SYSMENU style flag, 209, 210 

WS_TABSTOP style flag, 211 

WS_VISIBLE style flag, 24, 150, 165, 205, 
278, 374 

WS_VSCROLL style flag, 165, 167 
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X 
XOFF character, 550-51, 555 
XON character, 550-51, 555 
XTalk program, 518-31 
XTalk.c, 521-31 
XTalk.h, 519-21 
XTalk.rc, 519 
window, 518 


Z 


zero-delimited strings, 587 
zones, debug, 797-98 
Z-order, 88, 150, 151, 171, 375 
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